Problem

Anthropic's API natively supports defer_loading: true on tool definitions (docs). When set:

• Deferred tools are excluded from the system-prompt prefix (zero tokens upfront)
• Discovered tools are injected inline as tool_reference blocks
• Prompt caching is preserved — the prefix is untouched

opencode currently has no way to pass defer_loading: true through to the Anthropic API, neither from config nor from the tool.definition plugin hook.

Proposed solution

Option A: Plugin hook field

Add deferLoading?: boolean to the tool.definition hook output:

"tool.definition"?: (input: {
    toolID: string;
}, output: {
    description: string;
    parameters: any;
    deferLoading?: boolean;  // NEW — passed through to Anthropic API as defer_loading
}) => Promise<void>;

Option B: Config-level setting

Allow per-tool or per-MCP-server deferLoading in opencode.jsonc (similar to what the fork implements):

{
  "mcp": {
    "some-server": {
      "command": "...",
      "deferLoading": true  // all tools from this server are deferred
    }
  },
  "toolSearch": {
    "alwaysLoad": ["read", "write", "edit", "bash"]
  }
}

Option C: Both (recommended)

Config sets defaults, hook allows plugin overrides.

Why this is better than client-side filtering

• Prompt caching: Anthropic's server-side deferral preserves the cached prefix. Client-side filtering (like the fork's continue in resolveTools()) changes the tool list every time a tool is discovered, busting the cache.
• Native integration: tool_reference blocks are handled by Anthropic's infrastructure — no need to rebuild the tool list on discovery.
• Provider-agnostic path: The hook field can be ignored for non-Anthropic providers, making it a progressive enhancement.

Related

• [FEATURE]: Add hidden field to tool.definition hook output for tool suppression #23297 — Add hidden field to tool.definition hook (complementary — hidden for client-side suppression, deferLoading for server-side)
• feat: add mcp_lazy mode for on-demand MCP tool loading #8771, feat: mcp-search tool for lazy loading mcp #12520 — mcp_lazy mode PRs
• Anthropic docs: Tool search tool, Advanced tool use