Every tool definition you pass to Claude occupies context-window space before the model reads a single word of the user's request. Official docs note that a typical multi-server setup can burn roughly 55,000 tokens on definitions alone, and — more damaging — that Claude's tool-selection accuracy degrades once more than about 30–50 tools are loaded. Tool search attacks both problems: instead of loading every definition into context, Claude searches your tool registry and loads only what the task needs, typically cutting definition overhead by over 85%.
How deferred loading works
You still send every full tool definition in the tools array on every request — that part doesn't change. What changes is that you mark most tools with defer_loading: true. Deferred tools are not placed in Claude's context; they sit in a searchable registry on the server. When Claude needs a capability, it uses the tool search tool to query the registry, and matching definitions come back as tool_reference blocks that the API expands into full definitions automatically. Deferral controls what enters the context window, not what you transmit.
Two search variants exist, both generally available on the Claude API: tool_search_tool_regex_20251119, where Claude writes Python re.search() patterns (case-insensitive, up to 200 characters), and tool_search_tool_bm25_20251119, which takes natural-language queries up to 500 characters. Each search returns up to 5 matching tools by default; searches match against tool names, descriptions, argument names, and argument descriptions. At least one tool must remain non-deferred — normally the search tool itself; deferring everything returns a 400 error. The ceiling is high: up to 10,000 deferred tools per request.
Structuring metadata so the right tool wins
Since discovery runs over your tool metadata, that metadata is now retrieval content, and ordinary information-hygiene rules apply:
Name for the searcher, not the maintainer. create_invoice_draft will match a BM25 query like "draft an invoice"; svc_fin_op_7 will not. Consistent verb–noun naming across the registry helps both search variants.
Write descriptions with the words users use. Include synonyms and the business terms of your organization ("PO", "purchase order", "procurement request") — the description field is the richest matching surface.
Describe arguments too. Argument names and their descriptions are searchable, so "customer_id: the CRM account identifier" can be the detail that surfaces the right tool.
tool_references array — not an error — so silent misses show up only in behavior, not in status codes.Caching and cost behavior
Tool search is designed to be cache-friendly: discovered definitions are appended after your existing prompt, so a cached system-prompt prefix is preserved rather than invalidated. One constraint follows from this: a deferred tool cannot itself carry cache_control (that combination returns a 400). Billing is refreshingly simple — tool search is not metered as a separate server tool; the definitions it loads just bill as normal input tokens.
Platform availability
Tool search travels better than most server tools: generally available on the first-party Claude API, Claude Platform on AWS, Amazon Bedrock, and Google Vertex AI, with beta support on Microsoft Foundry. There is one meaningful Bedrock caveat: server-side tool search works only through the InvokeModel API, not the Converse API. On Claude Platform on AWS it works identically to the first-party API. It is also eligible for Zero Data Retention. If you run your own registry infrastructure, a client-side variant exists too — your application returns tool_reference blocks inside a standard tool_result, with every referenced tool defined (normally deferred) in tools.
Where to go next
Tool search pairs naturally with the MCP connector, since MCP servers are where tool registries balloon fastest. For the basics of how tool selection and tool_choice work, see the tool choice article, or check the feature matrix.