What Is the Tool Search Tool? Load Agent Tools On Demand

Agentic AIProtocols and integrationPublished By Simon Budziak

Tool search lets an AI model fetch tool definitions on demand instead of loading them all up front. The model searches a catalog, receives only the few tools it needs for the request, and calls them, which keeps its context window small as tool libraries grow.

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.

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.

This entry was drafted with AI assistance.

Frequently asked questions

Do I still send every tool definition with tool search?

Yes. You send all definitions on every request, marking most with defer_loading. The API needs them server-side to run the search, and only the ones Claude discovers enter its context.

When is tool search not worth using?

With fewer than 10 tools, when every tool is used on every request, or when the definitions are tiny. Anthropic's guidance names those cases as better served by standard tool calling.

Summarize this page with

See this working in a system we built