[FEATURE] Support for Tool Search Tool (defer_loading) to reduce token usage

[dctmfoo]

Summary

Add support for the Tool Search Tool beta feature to enable deferred tool loading and significantly reduce token consumption.

Problem

Currently, all tools (SDK + MCP) are loaded into context at session start. In my project, this consumes ~15,000-20,000 tokens for tool definitions alone, even when most tools aren't needed for the current query.

My current setup:

• 12 SDK tools: ~6,000 tokens
• 8 MCP tools (Google Workspace): ~5,285 tokens
• Total tools overhead: ~11,000+ tokens per request

Proposed Solution

Support the defer_loading: true option and Tool Search Tool as documented at:
https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool

This would require:

1. Beta header support in SDK options:

   • advanced-tool-use-2025-11-20
   • mcp-client-2025-11-20

2. Option to pass defer_loading config for individual tools or as default

3. Support for mcp_toolset with default_config for MCP servers:

{
  type: "mcp_toolset",
  mcp_server_name: "my-server",
  default_config: {
    defer_loading: true
  },
  configs: {
    "frequently_used_tool": { defer_loading: false }
  }
}

Expected Benefit

According to Anthropic's documentation:

• Up to 85% reduction in tool token usage
• Improved accuracy on tool selection with large tool libraries (Opus 4.5: 79.5% → 88.1%)

Workaround

Currently the only workaround is to manually reduce the number of tools configured, which limits functionality.

Related

• Claude Code has ENABLE_TOOL_SEARCH setting that enables this feature
• Feature request for Claude Code: Feature Request: Lazy Loading for MCP Servers and Tools (95% context reduction possible) claude-code#7336
• Tool Search Tool docs: https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool

[Blakefolgado]

Please can this be added urgently as I use 30k tokens to say one message. This needs to get under control. Same for skills with agent sdk.

[tabletenniser]

+1, is there any ETA on when defer_loading can be supported by the Typescript SDK?

[mo-silent]

+1, is there any ETA on when defer_loading can be supported by the Python SDK?

[seunggs]

+1 this should be prioritized - the token cost is huge without this in any real use cases.

[SimonAKing]

+1

[bilby91]

Is this being prioritized ?

Thanks!

[moro256]

+1

[shaggy8871]

+10

[parkghost]

It should be there.

https://platform.claude.com/docs/en/agent-sdk/mcp#mcp-tool-search

[qing-ant]

This is now supported. Tool search is enabled by default in the Agent SDK and works with all registered tools (MCP servers and custom SDK MCP servers).

When tool search is active, tool definitions are withheld from the context window. The agent receives a summary of available tools and searches for relevant ones when the task requires a capability not already loaded. Only the 3-5 most relevant tools are loaded into context per search step.

You can configure the behavior via the ENABLE_TOOL_SEARCH environment variable:

for await (const message of query({
  prompt: "Find and run the appropriate database query",
  options: {
    mcpServers: { /* your servers */ },
    allowedTools: ["mcp__enterprise-tools__*"],
    env: {
      ENABLE_TOOL_SEARCH: "auto:5" // Activate when tools exceed 5% of context
    }
  }
})) { /* ... */ }

Value	Behavior
(unset)	Tool search is always on (default)
"true"	Same as unset
"auto"	Activates when tool definitions exceed 10% of the context window
"auto:N"	Custom percentage threshold
"false"	Disabled; all tool definitions loaded into context

Full documentation: https://platform.claude.com/docs/en/agent-sdk/tool-search

---

Generated by Claude Code