Add a tool search tool to tools and set defer_loading: true on the tools that should not load up front. Claude starts with only the search tool and your non-deferred tools, searches the catalogue when it needs more, and the API loads the matches.
How it works
There are two variants. With tool_search_tool_regex_20251119, Claude writes Python regex patterns of up to 200 characters. With tool_search_tool_bm25_20251119, it writes natural language queries of up to 500 characters. Both search tool names, descriptions, argument names and argument descriptions.
A search returns matches as tool_reference blocks, 5 by default. Claude can set limit in its search input to any integer from 1 to 10,000. The API expands each reference into the full definition, and Claude then calls the tool as usual. A request can hold up to 10,000 deferred tools. A search that matches nothing returns an empty list, not an error.
What defer_loading does and does not do
defer_loading controls what enters Claude's context, not what you send. You still send every full definition in tools on every request, because the API needs them to run the search and expand references. If you remove deferred tools and add them back after discovery, the request fails with Tool reference '...' not found in available tools.
At least one tool must stay non-deferred, or the API returns a 400. Never defer the search tool itself, and keep your 3 to 5 most used tools loaded. For MCP servers, set defer_loading in the mcp_toolset entry's default_config or configs.
Caching and platforms
Deferred tools are left out of the system-prompt prefix, and a discovered tool is expanded inline in the conversation, so adding or discovering deferred tools does not break your prompt cache. A deferred tool cannot also carry cache_control; put the breakpoint on a non-deferred tool. On Amazon Bedrock, server-side tool search works only through the InvokeModel API, not the Converse API.
Where the exam catches people
Believing deferred definitions can be left out of the request: every definition must be sent; defer_loading only hides it from context.
Believing five results is a hard cap: it is the default, and Claude can raise limit.
Believing every tool can be deferred: at least one must stay loaded, and the search tool itself must never be deferred.
Believing tool search works through Bedrock's Converse API: on Bedrock it needs InvokeModel.