Claude Code Tool Search: Defer MCP Tools, Save Context

I connected a sixth MCP server and my sessions got measurably worse before they got better. Not because any single tool was bad — because every one of those servers was publishing its full tool schemas into the system prompt on every request, and the model was reading a catalogue before it read the question.

Tool search is the fix, and it has been the default long enough that most people never see the problem. This post is for the case where you do: when you are running a lot of servers, when you are behind a gateway that silently turns deferral off, or when you want one server's tools present on every turn. It covers the four configuration values, the alwaysLoad escape hatch, the prompt-cache consequence that nobody mentions, and what MCP server authors should do about it.

Tool definitions are the expensive part, and they sit in the worst layer

Claude Code orders each request so that rarely-changing content comes first: the system prompt with its tool definitions, then project context, then the conversation. That ordering is what makes prompt caching work. Tool definitions sit in the very first layer, which means two things at once — they are paid for on every request, and any change to them invalidates everything cached behind them.

So a server with forty verbose tool schemas is not a one-time cost you pay at startup. It is rent, charged on every turn, on a layer where a mid-session reconnect can also cost you the entire cached conversation. Claude Code imposes no fixed per-server tool cap; the practical limit is your context budget, and that limit arrives faster than people expect.

Four values, and only one of them is a compromise

Tool search is enabled by default: MCP tools are deferred and discovered on demand, with only names and server instructions loaded upfront. The environment variable exists for the cases where the default is wrong for your setup.

What each value does:

# Tool search is ON by default. These override it.

# Threshold mode: load definitions upfront while they total
# under 10% of the context window, defer all of them past that.
ENABLE_TOOL_SEARCH=auto claude

# Same, with your own percentage (N is 0-100).
ENABLE_TOOL_SEARCH=auto:5 claude

# Force deferral even through a proxy. Requests FAIL on proxies
# that do not support tool_reference blocks — that is the trade.
ENABLE_TOOL_SEARCH=true claude

# Load everything upfront, the pre-tool-search behaviour.
ENABLE_TOOL_SEARCH=false claude

# Or put it in the env block of settings.json so it applies
# to every session rather than the one you remembered to flag.

alwaysLoad, and what it costs at startup

Some tools Claude needs on effectively every turn, and making it run a search step first is pure latency for no context saving. The alwaysLoad field exempts a server from deferral entirely, and it is available on every server type. Use it for a small number of tools, because each upfront tool consumes context that would otherwise be available for your actual conversation.

// .mcp.json — exempt ONE server from deferral. Every tool it
// exposes loads at session start regardless of ENABLE_TOOL_SEARCH.
{
  "mcpServers": {
    "core-tools": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "alwaysLoad": true
    }
  }
}

// Cost: alwaysLoad makes STARTUP WAIT for that server's tools,
// capped at the standard 5-second connect timeout, because they
// have to be present when the first prompt is built. Other
// servers connect in the background.
//
// A server can also mark a SINGLE tool always-loaded by putting
// "anthropic/alwaysLoad": true in that tool's _meta object.

// To remove the search step itself rather than the deferral:
{
  "permissions": { "deny": ["ToolSearch"] }
}

The prompt-cache consequence nobody mentions

This is the part I did not expect, and it changed how I think about MCP stability. When tools are deferred, a server connecting, disconnecting or changing its tool list only appends new content — it does not disturb anything already cached. When tools are loaded into the prefix, any change to them invalidates the cache and the next request re-reads your entire conversation.

That matters because MCP servers disconnect without you doing anything. A stdio server's process exits, an HTTP session expires, a server reconnects after a transient failure, or a connected server pushes a dynamic tool update that changes its list. With deferral on, none of that costs you the conversation cache. With deferral off, a flaky server is quietly charging you a full uncached turn every time it blinks.

Where it silently turns itself off

The default is deferral, but Claude Code falls back to upfront loading in several situations, and none of them announce themselves:

• When the base URL points at a non-first-party host, because most proxies do not forward tool_reference blocks. Set the variable explicitly to override the fallback.
• On Microsoft Foundry deployments hosted on Azure, which reject it server-side. The environment variable cannot override this, because the rejection comes from the deployment.
• On Google Cloud's Agent Platform models earlier than the Claude 4.5 generation, whose serving stacks reject the required beta header.
• When the experimental-betas variable is set, which keeps tool search off and cannot be overridden by setting the tool-search variable yourself.

If you are writing an MCP server

Deferral changes what your server should publish. Claude only sees tool names and your server instructions until it decides to search, so the instructions field is doing the job a skill description does — it has to explain when Claude should come looking:

• Say what category of tasks your tools handle, in the first sentence rather than the third.
• Say when Claude should search for them, not just what they are.
• Keep it short: tool descriptions and server instructions are both truncated at 2 KB, so put the critical detail near the start.

Turning off the search step without turning off deferral

These are two different things and it is worth separating them. Deferral is about what loads into the prefix; the ToolSearch tool is how Claude retrieves a deferred definition later. You can deny the tool with a permission rule, which leaves deferral in place but removes Claude's ability to fetch what was deferred — useful when you want the context saving and have made every tool Claude actually needs always-loaded.

For organisations, the controls sit somewhere else again. Managed settings can keep tool search on across an organisation, and managed MCP configuration governs which servers users may connect to at all. If your goal is bounding context cost across a team rather than in your own session, that pair is the lever, not the environment variable.

The rule I use now is simple: leave tool search on, mark the two or three tools you genuinely use every turn as always-loaded, and treat a persistently high cache-creation count as a signal that something in the tool layer is moving. The context saving is the headline, but the reason I care is the cache — deferral is what stops an unreliable MCP server from quietly costing you your conversation history every few minutes.