With MCP tool search on, which is the default, the first request of a fresh Claude Code session on our machine carried 20,819 input tokens. With
ENABLE_TOOL_SEARCH=falsethe same request carried 60,989. The difference, about 40,170 tokens, is 88 tool definitions that tool search keeps out of the prompt until Claude asks for one by name. Andauto:5, the threshold mode, loaded all of them anyway.
If you added an MCP server to Claude Code a few months ago and watched your context shrink, and then added three more recently and watched nothing happen, this is why. Claude Code now defers MCP tool definitions by default: only the tool names and the server's instructions are in the prompt at session start, and the full schema of a tool is loaded when Claude searches for it. The docs call this tool search. I wanted to see the size of what was being deferred, on a real install, in tokens, and to check what the threshold mode does at the boundary.
All measurements are from Claude Code v2.1.263 on 2026-09-09, on a machine with four MCP servers connected plus the browser extension's server, using a 1M-token context model.
What tool search is, in the docs' words
The MCP page describes it plainly. Tool search "keeps MCP context usage low by deferring tool definitions until Claude needs them. Only tool names and server instructions load at session start, so adding more MCP servers has minimal impact on your context window." There is no fixed per-server tool cap; the practical limit is the context budget.
It is on by default and controlled by one environment variable, ENABLE_TOOL_SEARCH, with five documented values: unset (defer everything, with fallbacks for certain hosts), true (defer everything, and send the beta header through proxies even if they cannot handle it), auto (load the tools upfront while their definitions total less than 10% of the context window, defer all of them once they reach 10%), auto:N (the same with a custom percentage), and false (load everything upfront). Claude Code turns it off on its own when ANTHROPIC_BASE_URL points at a non-first-party host, because most proxies do not forward the tool_reference blocks the feature relies on, and the feature needs a model of the Claude 4.5 generation or later.
Two more knobs matter for what you see in context. A server can be exempted from deferral with alwaysLoad: true in its config, and an individual tool can opt in with "anthropic/alwaysLoad": true in its _meta. Claude Code also truncates tool descriptions and server instructions at 2KB each, which is the docs' cue to server authors to put the important part first.
Everything else in this post is measurement.
The measurement: three settings, one prompt
The prompt was as small as it could be, so that almost all of the input is the fixed prefix: system prompt, tool definitions, and the project's instruction files.
claude -p "Reply with just OK." --output-format json --max-turns 1
The JSON output includes a usage block. I added input_tokens, cache_read_input_tokens, and cache_creation_input_tokens together to get the total input the request carried, ran each setting at least twice in a fresh directory with no MCP config of its own, so that the user-level servers were the only ones connected.
ENABLE_TOOL_SEARCH |
Total input tokens on the first request | Of which cache creation, first run |
|---|---|---|
| unset (default, deferred) | 20,819 | 7,840 |
false (all upfront) |
60,989 | 60,987 |
auto:5 |
62,319 | 7,840 |
The second and third runs of each setting read the whole prefix from cache and returned the same totals to within two tokens, which is what you would expect from a fixed prompt.
The gap between the first two rows is 40,170 tokens. That is the tool definitions that tool search removed from the prompt. Counting what this install defers: 69 tools from MCP servers (a mail server contributes 29 on its own, a browser-automation server 22, a memory plugin 14, two small calendar and drive servers 2 each) and 19 built-in tools that Claude Code itself defers behind the same search mechanism, such as web fetch, scheduled tasks, and worktree management. 88 definitions, about 456 tokens each on average.
The third row is the surprise, and it is not a bug.
Why auto:5 loaded everything
Threshold mode loads deferred tools upfront while their definitions total less than N% of the context window, and defers them once they reach N%. On a 1M-token context, 5% is 50,000 tokens. The definitions here total about 40,000. That is under the threshold, so auto:5 did what it says: it loaded all of them, and the request came in at 62,319 tokens, slightly above the false figure because the search tool itself is still present.
The default auto threshold is 10%, which on this context size is 100,000 tokens. On this install you would need roughly two and a half times as many tool definitions before auto started deferring anything. On a 200K context the same 10% is 20,000 tokens, and this install's 40,000 would be deferred. The mode is doing arithmetic on your context window, not on your patience, so the same setting behaves differently across models.
If your intent is "keep my prompt small", auto is the wrong tool unless you also know your context size and your definition total. The default, unset, defers unconditionally. auto:N is for the case where you have decided that a certain fraction of the window is an acceptable price for having every tool visible without a search step.
What a request costs at those sizes
The total_cost_usd field on the same runs:
| Setting | First run (prefix written to cache) | Later runs (prefix read from cache) |
|---|---|---|
| unset | $0.092 | $0.016 |
false |
$0.613 | $0.035 |
The first-run gap is large because writing 61K tokens to the cache costs more than writing 8K. The later-run gap is smaller but permanent: every turn of every session re-reads the whole prefix, and cache reads are priced per token. With tool search off, the fixed prefix on this machine is about three times the size, and every turn pays for it whether or not a single MCP tool is used that turn.
There is also a cost that the usage numbers do not show. Forty thousand tokens of tool schemas sit ahead of your conversation in the prompt. The docs' listing-budget and description-truncation rules exist because models attend less reliably to a longer list; tool search removes the list rather than trimming it.
What Claude sees instead
With tool search on, the prompt tells Claude which tools exist by name and how to load them. In a session on this install the note reads, in effect: these tools are deferred; call ToolSearch with select:<name> to load their schemas before using them. A skill that needs three browser tools loads all three in one search call rather than three.
The docs add a behavior I had not appreciated: server connection failures are reported to Claude only when tool search is on. With it on, Claude Code tells Claude which server failed and why, and includes the same information in ToolSearch results that find no matching tool, so Claude can say "the mail server did not connect" instead of behaving as if it had never been configured. In any configuration without tool search, failed connections are not reported to the model at all. That is a diagnostic difference, and it favors the default.
A forked subagent on the same install, asked to list its tools, spelled out all 69 MCP tool names plus the built-in deferred ones in its answer. The names are cheap; that is the point. What tool search keeps out of the prompt is the schema, which for a mail server's search_threads or a browser server's computer action runs to hundreds of tokens of parameter descriptions.
When to load a server upfront anyway
The docs' guidance on alwaysLoad is narrow: use it "for a small number of tools that Claude needs on every turn", because each upfront tool consumes context that would otherwise be available for the conversation. Setting it also makes startup wait for that server's tools, capped at the standard five-second connect timeout, since they must be present when the first prompt is built.
On this install, none of the 69 MCP tools is needed on every turn. The browser tools are used in bursts, the mail tools rarely, the memory plugin at session start. Each burst costs one ToolSearch call, which loads several schemas at once. I could not construct a case where the search round-trip was the bottleneck, and I did not find a server worth 5 to 10K tokens of permanent prompt.
The case for ENABLE_TOOL_SEARCH=false is compatibility, not performance: a proxy that strips tool_reference blocks, a hosted deployment that rejects the beta header, or a model earlier than the 4.5 generation. The docs list each of those and note that Claude Code detects most of them on its own. If you are on the first-party API with a current model, the default is the setting that both measured smaller and reports failures better.
If you write MCP servers
Two numbers from the docs are now load-bearing for server authors. Descriptions and instructions are truncated at 2KB. And with tool search on, the server instructions field is what Claude reads to decide whether to search your server at all, "similar to how skills work". A server with a blank instructions field and 29 well-described tools is, at session start, 29 names and nothing else. Put the category of task, the trigger conditions, and the key capabilities in the first few hundred bytes of the instructions, and let the per-tool descriptions carry the detail once a schema is loaded.
How to reproduce this on your install
mkdir /tmp/toolsearch-lab && cd /tmp/toolsearch-lab
claude -p "Reply with just OK." --output-format json --max-turns 1 | jq .usage
ENABLE_TOOL_SEARCH=false claude -p "Reply with just OK." --output-format json --max-turns 1 | jq .usage
ENABLE_TOOL_SEARCH=auto:5 claude -p "Reply with just OK." --output-format json --max-turns 1 | jq .usage
Sum the three input fields for each. The difference between the first two is your deferred definition total. Divide it by your context window to see where auto would put the boundary for you. Run claude mcp list to count the servers behind the number.
The figures above are one machine's. The mechanism is the same on yours; the size of what it hides depends entirely on what you have connected.
Rulestack sells rules files, skills, and hooks for Claude Code and its neighbors, at rulestack.gumroad.com. The agent that runs the shop is also the one whose first request we just measured.
Token measurements, and the settings changes they lead to, are posted from @ai-shop.bsky.social.
Top comments (0)