What you will be able to do
- Configure deferred tool loading with the tool search tool and explain what defer_loading actually changes
- Choose an ENABLE_TOOL_SEARCH setting for an Agent SDK agent
- Restrict a subagent's tools so that it only has the capabilities its role needs
- Match a source of context pressure to the right remedy: tool search, programmatic tool calling, prompt caching or context editing
1.Loading tools on demand with tool search
Some agents really do need a large catalogue, for example an enterprise assistant spanning dozens of systems. For these, the platform offers the tool search tool. Claude doesn't receive every definition up front. It searches the catalogue and loads only what the current request needs. The search covers tool names, descriptions, argument names and argument descriptions. The documentation says this typically cuts definition tokens by over 85 percent, because only the 3–5 tools a request needs are loaded. It also keeps selection accuracy high across thousands of tools.
There are two variants. tool_search_tool_regex_20251119 has Claude write regex patterns. tool_search_tool_bm25_20251119 has Claude search with natural-language queries. Claude Opus 4.1 and earlier models don't support either.
{
"name": "get_weather",
"description": "Get current weather for a location",
"input_schema": {
"type": "object",
"properties": {
"location": { "type": "string" },
"unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
},
"required": ["location"]
},
"defer_loading": true
}A common point of confusion is that defer_loading controls what enters the context window, not what goes in the request. You still send every tool's full definition on every request, because the API needs them server-side to run the search. Searches return tool_reference blocks, up to five by default, and the API expands each one into the full definition.
The configuration rules are:
- At least one tool must stay non-deferred, and that is normally the search tool. Never set defer_loading: true on the tool search tool itself.
- Keep your 3–5 most frequently used tools non-deferred, so Claude can call them without searching first.
- Deferred tools are excluded from the system-prompt prefix, so prompt caching is preserved.
The cost is latency. Each discovery adds one extra turn to look up a tool, and in exchange baseline context usage drops a lot.
Checkpoint 1 of 6· Check yourself
A developer enables tool search and removes the deferred tools' definitions from the tools array to save bandwidth. What happens?
defer_loading only keeps definitions out of Claude's context. The request must still contain every definition so that the API can search them and expand tool_reference blocks.
“You still send every tool's full definition in the tools array on every request, including the deferred ones.”Source: platform.claude.com
2.Tool search in the Agent SDK
In the Claude Agent SDK, tool search is mostly automatic. On Claude Opus 4.5, Sonnet 4.5, Haiku 4.5 and later models it is on by default, and definitions are deferred and discovered on demand. The catalogue can hold up to 10,000 tools. Each search returns up to the five most relevant. You control the behaviour with the ENABLE_TOOL_SEARCH environment variable.
| Value | Behaviour |
|---|---|
| (unset) | On: definitions deferred and discovered on demand, with fallbacks to upfront loading on some deployments |
| true | Always on, except where the server side forces upfront loading. The SDK sends the beta header through proxies, and requests fail on proxies that don't support tool_reference blocks |
| auto | Activates when deferrable definitions reach 10% of the model's context window. Below that, the SDK loads every tool definition into context upfront |
| auto:N | Same as auto, with a custom percentage. Lower values activate sooner |
| false | Off: every definition loads into context on every turn |
Choosing auto or auto:N lets a configuration adjust to its own size. A small tool set loads up front and never pays the search turn. Once connected MCP servers push the deferrable definitions past the threshold, search switches on. Note that false brings back the monolithic behaviour, where every definition is loaded on every turn. If a large configuration sets this value, check whether that was deliberate.
The SDK's own example also shows the permission side of an MCP connection. It sets allowedTools to mcp__enterprise-tools__*, and the source comments that this wildcard pre-approves all tools from that server. Pre-approval is a separate setting from tool search. The wildcard covers every tool the server exposes, now and as the server grows, so when you evaluate a configuration, check how broad an allowedTools pattern is as well as how many definitions are loaded.
Checkpoint 2 of 6· Fill the gap
Complete the Python configuration so that tool search activates once deferrable definitions reach 5% of the context window.
env={
"ENABLE_TOOL_SEARCH": " ? " # Activate tool search when deferrable definitions reach 5% of context
},auto:N activates tool search when deferrable definitions reach N percent of the context window. The value true would keep tool search always on, with no threshold.
Source: code.claude.comSources3
3.Scoping tools per agent
Tool search handles a large catalogue for one agent. Another way to reduce bloat is to avoid giving every agent the whole catalogue in the first place. In the Agent SDK, a subagent's AgentDefinition can limit it to specific tools, which reduces the risk of unintended actions. In the SDK's example, a code-reviewer subagent gets only Read, Grep and Glob, so it can analyse code but can never modify it. A test-runner subagent gets Bash because its job is running test commands.
The default matters when you evaluate a configuration. If tools is omitted, the subagent inherits every tool available to subagents. A subagent definition without a tools list is therefore unscoped.
| Field | Effect |
|---|---|
| tools | Allowed tool names. If omitted, the agent inherits every tool available to subagents |
| disallowedTools | Removes tools. mcp__server or mcp__server__* removes a whole server; mcp__* removes every MCP tool |
| mcpServers | MCP servers available to this agent, by name or inline config |
| skills | Skills preloaded into context at startup. Unlisted skills stay invocable through the Skill tool |
| permissionMode | Permission mode for tool execution within this agent. The subagent inheritance rules decide when it applies |
Two of these fields control an agent's MCP surface. disallowedTools removes tools from the agent's tool set, and it also accepts server-level patterns. mcp__server or mcp__server__* removes every tool from that one server, so a pattern such as mcp__legacy__* drops a whole legacy server from the agent. mcp__* removes every MCP tool from any server. mcpServers lists the MCP servers available to this agent, by name or inline config, so an agent only sees the servers it is given.
Keep two ideas apart. tools and disallowedTools shape which tools an agent has. allowedTools in the SDK examples is commented as auto-approving tools, and a wildcard such as mcp__enterprise-tools__* pre-approves everything a server offers. permissionMode is a separate field that sets the permission mode for tool execution within an agent. The documentation says only that the subagent inheritance rules decide when it applies, so this lesson does not go further into individual modes.
Checkpoint 3 of 6· Check yourself
A reviewer finds a documentation-checking subagent whose AgentDefinition has a description and a prompt but no tools field. What capability does it have?
Leaving out tools does not restrict the subagent. It inherits the full set, which is the opposite of least privilege for a review-only role.
“Array of allowed tool names. If omitted, inherits every tool available to subagents”Source: code.claude.com
Checkpoint 4 of 6· Exam question
A lead agent has allowedTools: ["Read", "Write", "Edit", "Bash", "Agent"] for its own broad development work. The team also defines a code-reviewer subagent that should only ever read and search code, never write files or run shell commands, regardless of what the lead agent is permitted to do. How should the subagent be configured to enforce this?
Correct answer: A — Define the subagent with its own tools: ["Read", "Glob", "Grep"] field in its AgentDefinition, independent of the lead agent's allowedTools.
- A. Correct. Custom subagents define their own tools field, which scopes exactly what that subagent can call, independent of the lead agent's broader allowedTools.
- B. Incorrect. Subagents do not automatically inherit a subset of the lead agent's tool list; without an explicit tools field, a subagent's capability is defined by its own configuration.
- C. Incorrect. CLAUDE.md is contextual guidance, not a tool permission mechanism, and subagents do not inherit tool permissions purely from prose instructions.
- D. Incorrect. permissionMode is a session-level setting; switching it on the lead agent affects approval behavior generally, it does not selectively restrict only the subagent's tool access.
Sources4
4.Matching the remedy to the source of pressure
Not every context problem is tool bloat. The platform documentation lists four approaches, and each one targets a different source of tokens. Use the one that matches where your tokens are actually going.
| Approach | What it reduces | When it fits |
|---|---|---|
| Tool search | Tool definitions loaded upfront | Large toolsets (20+ tools) where most tools aren't needed every turn |
| Programmatic tool calling | tool_result roundtrips | Chains of tool calls that can execute as a single script |
| Prompt caching | Token cost of repeated tool definitions | Stable toolsets across many requests |
| Context editing | Old tool_result blocks in history | Long conversations where early results are no longer relevant |
Prompt caching is a common trap when you evaluate bloat. It lowers what you pay for repeated definitions, but it doesn't reduce the number of tokens in context. A cached 60-tool set therefore still has the selection-accuracy problem. What reduces the choice Claude faces is loading fewer definitions with tool search, or giving each agent fewer tools, for example by scoping a subagent with tools or disallowedTools.
Approving tools is a different thing from trimming them. The SDK examples describe allowedTools as auto-approving tools, and a server wildcard as pre-approving all tools from that server. To shrink what an agent has available, use the tool lists and MCP patterns from the previous section, and check any wildcard pre-approval for how much it covers.
The approaches can be combined. A suggested starting point for a high-volume agent is: cache tool definitions from day one, add tool search once the tool set grows past about 20 tools, add context editing when conversations run long, and consider programmatic tool calling for repeated chains of small calls.
Checkpoint 5 of 6· Match them up
Match each symptom to the approach that targets it
Tap a term, then the definition that fits it.
Each approach reduces a different thing: upfront definitions, tool_result roundtrips, stale history, or the cost of repeated definitions.
“Prompt caching doesn't reduce the number of tokens in context, but it reduces what you pay for them on subsequent requests.”Source: platform.claude.com
Checkpoint 6 of 6· Exam question
During a capability-bloat review of an agent configuration, which of the following actions would correctly reduce the agent's unnecessary tool surface? (Select all that apply.)(Select 3)
Correct answers: A, B, C — Disconnect MCP servers whose tools are never used by the agent's actual triage workflow, removing them from the session entirely.; Scope deny rules to specific MCP servers, e.g. disallowedTools: ["mcp__legacy__*"], rather than leaving all servers reachable.; Set disable-model-invocation: true on any skill that performs a side-effecting action the user should trigger manually.
- A. Correct. Disconnecting unused MCP servers removes their tool definitions from the session, which is an enforced reduction in the agent's actual capability surface.
- B. Correct. A deny rule scoped to a specific server's tools removes that server's tools from the request, directly narrowing what the agent can invoke.
- C. Correct. Hiding side-effecting skills from automatic model invocation ensures they only run on explicit user request, reducing unintended capability exposure.
- D. Incorrect. A CLAUDE.md note is guidance Claude may or may not follow; it does not remove any tool from the agent's available surface, so the underlying bloat remains.
- E. Incorrect. bypassPermissions removes approval friction but does not reduce which tools are available; it actually increases risk since any available tool, including unnecessary ones, runs without checks.
- F. Incorrect. An unanchored allowedTools: ["*"] entry is ignored with a startup warning and does not auto-approve anything, so this configuration does not behave as described and does not reduce bloat.
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.Setting defer_loading: true means the deferred tool definitions can be left out of the request.Why is that wrong?
defer_loading only keeps definitions out of Claude's context window. Every full definition must still be sent so that the API can search and expand them.
Covered in Loading tools on demand with tool search
2.Prompt caching fixes a bloated tool set because the definitions no longer cost much.Why is that wrong?
Caching cuts the price of repeated definitions, but the tokens stay in context and Claude still has to choose among every tool.
3.A subagent with no tools field is restricted to a safe minimum.Why is that wrong?
Omitting tools means the subagent inherits every tool available to subagents. Scoping requires an explicit tools list or disallowedTools.
Covered in Scoping tools per agent
Sources
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“Tool search typically reduces this by over 85 percent, loading only the 3–5 tools Claude needs for a given request.”
↩︎ Loading tools on demand with tool search“Never set defer_loading: true on the tool search tool itself.”
↩︎ Loading tools on demand with tool search“Keep your 3–5 most frequently used tools non-deferred so Claude can call them without searching first.”
↩︎ Loading tools on demand with tool search“The prefix is untouched, so prompt caching is preserved.”
↩︎ Loading tools on demand with tool search“Claude Opus 4.1 and earlier models don't support the tool search tool.”
↩︎ Loading tools on demand with tool search“defer_loading controls what enters the context window, not what you send in the request”
↩︎ Exam trap 1“You still send every tool's full definition in the tools array on every request, including the deferred ones.”
↩︎ Checkpoint - 2.
“This trades a small amount of latency (one extra turn to look up a tool) for a large reduction in baseline context usage.”
↩︎ Loading tools on demand with tool search“Prompt caching doesn't reduce the number of tokens in context, but it reduces what you pay for them on subsequent requests.”
↩︎ Matching the remedy to the source of pressure“These approaches compose.”
↩︎ Matching the remedy to the source of pressure“Prompt caching doesn't reduce the number of tokens in context, but it reduces what you pay for them on subsequent requests.”
↩︎ Exam trap 2 - 3.
“Claude Opus 4.5, Sonnet 4.5, Haiku 4.5, and later: tool search is on by default.”
↩︎ Tool search in the Agent SDK“When the total reaches 10% of the window, tool search activates.”
↩︎ Tool search in the Agent SDK“Maximum tools: 10,000 tools in your catalog”
↩︎ Tool search in the Agent SDK“requests fail on proxies that don’t support tool_reference blocks.”
↩︎ Tool search in the Agent SDK“Below that, the SDK loads every tool definition into context upfront.”
↩︎ Tool search in the Agent SDK“Wildcard pre-approves all tools from this server”
↩︎ Tool search in the Agent SDK“Wildcard pre-approves all tools from this server”
↩︎ Matching the remedy to the source of pressure - 4.https://code.claude.com/docs/en/agent-sdk/subagentsOfficial docs
“subagents can be limited to specific tools, reducing the risk of unintended actions.”
↩︎ Scoping tools per agent“Array of allowed tool names. If omitted, inherits every tool available to subagents”
↩︎ Scoping tools per agent“mcp__server or mcp__server__* removes every tool from that server, and mcp__* removes every MCP tool from any server”
↩︎ Scoping tools per agent“MCP servers available to this agent, by name or inline config”
↩︎ Scoping tools per agent“Permission mode for tool execution within this agent. The subagent inheritance rules decide when it applies”
↩︎ Scoping tools per agent“Auto-approve these tools”
↩︎ Scoping tools per agent“Array of allowed tool names. If omitted, inherits every tool available to subagents”
↩︎ Exam trap 3