Skip to main content
Tool search enables your agent to work with hundreds or thousands of tools by dynamically discovering and loading them on demand. Instead of loading all tool definitions into the context window upfront, the agent searches your tool catalog and loads only the tools it needs. This approach solves two challenges as tool libraries scale:
  • Context efficiency: Tool definitions can consume large portions of the context window (50 tools can use 10-20K tokens), leaving less room for actual work.
  • Tool selection accuracy: Tool selection accuracy degrades with more than 30-50 tools loaded at once.

​
How tool search works

Tool search is on by default, with the exceptions listed in Configure tool search. When it 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. Up to five of the most relevant tools are loaded into context by default, where they stay available for subsequent turns until the SDK compacts the messages where the agent discovered them. After that compaction, the agent searches for those tools again when it next needs them. Tool search adds one extra round-trip each time Claude searches for tools, but for large tool sets this is offset by smaller context on every turn. With fewer than ~10 tools whose definitions fit comfortably in the context window, loading everything upfront is typically faster. For details on the underlying API mechanism, see Tool search in the API.
Tool search isn’t supported on Microsoft Foundry deployments hosted on Azure, which reject it server-side: the SDK detects the rejection and loads tool definitions upfront for that deployment instead. ENABLE_TOOL_SEARCH can’t override this, since the rejection comes from the deployment itself.
Tool search is on by default. For models on the SDK’s unsupported-model list, the SDK loads tool definitions upfront instead, and no ENABLE_TOOL_SEARCH value overrides that. On Google Cloud’s Agent Platform, the SDK decides by model generation:
  • Claude Opus 4.5, Sonnet 4.5, Haiku 4.5, and later: tool search is on by default.
  • Earlier Agent Platform models: the SDK loads tool definitions upfront, because their serving stacks reject the required beta header. ENABLE_TOOL_SEARCH can’t override this.
Before Claude Code v2.1.221, the SDK disabled tool search for all models on Google Cloud’s Agent Platform unless you set ENABLE_TOOL_SEARCH. The SDK also disables tool search when ANTHROPIC_BASE_URL points to a non-first-party host, since most proxies don’t forward tool_reference blocks. You can override that default with the ENABLE_TOOL_SEARCH environment variable: