Why does tool search exist?
Every tool definition costs tokens, and a large catalog hurts twice. Anthropic’s tool search page says a typical multiserver setup (GitHub, Slack, Sentry, Grafana and Splunk) can use about 55k tokens of definitions before any work starts, and that Claude’s ability to pick the right tool degrades past 30 to 50 available tools (Anthropic, tool search tool, read 19 November 2026). Tool search moves tool selection from a prompt-size problem to a lookup problem. The page says it typically cuts that overhead by over 85 percent, loading the 3 to 5 tools a request needs. It is one case of the just-in-time retrieval idea in context engineering.
How does the tool search tool work?
You add a tool search tool to the tools list, supply every other tool definition and set defer_loading: true on the ones that should not load up front. At least one tool must stay non-deferred, normally the search tool itself. When the model needs something, it searches, the API returns matches as tool_reference blocks (up to 5 by default), expands them into full definitions and the model calls the tool as in ordinary tool calling.
| Variant | Type string | How the model queries |
|---|---|---|
| Regex | tool_search_tool_regex_20251119 |
A Python regex pattern, up to 200 characters |
| BM25 | tool_search_tool_bm25_20251119 |
A natural language query, up to 500 characters |
| Custom | Your own tool returning tool_reference blocks |
Whatever you build, such as embeddings |
Both variants search tool names, descriptions, argument names and argument descriptions. A request can carry up to 10,000 deferred tools (Anthropic, read 19 November 2026).
How does tool search work with MCP?
MCP tools are deferred per server, not per definition. Tools from an MCP server connected through Anthropic’s MCP connector are deferred at the server level, by setting defer_loading in the mcp_toolset entry’s default configuration, or per tool, rather than on each definition (Anthropic, tool search tool, read 19 November 2026). That makes it practical to attach several large servers without paying for every tool in every turn.
When should you use tool search?
Use tool search once a tool catalog gets large. Anthropic’s guidance is to use it with 10 or more tools, definitions above 10k tokens, falling selection accuracy, several MCP servers or a catalog that keeps growing, and to prefer standard tool calling for under 10 tools or tiny definitions (Anthropic, tool search tool, read 19 November 2026). Keep your 3 to 5 most-used tools non-deferred so they need no search. Name tools with a consistent prefix by service, such as github_ or slack_, so one search finds the group, and put task keywords in descriptions. Tool search is not metered as a separate server tool, and the definitions it loads count as ordinary input tokens. A deferred tool cannot also carry cache_control. For calling many tools from code, see programmatic tool calling and the post on it.