The MCP context tax: how to stop paying for tools your agent never calls

Connect your agent to a handful of MCP servers and something quietly expensive happens: before it reads a single word of the user’s question, it has already processed tens of thousands of tokens of tool definitions. You pay that on every request, for every tool, including the ones it will never call. Anthropic now ships two generally-available features that attack this from opposite ends — load fewer definitions, and keep tool results out of the model entirely. Here’s what each actually does, the numbers behind them, the one that’s uniquely kind to your prompt cache, and the restriction that catches nearly everyone.

The tax you pay before the agent does anything

The first two posts in this series dealt with context that an agent accumulates — stale tool results piling up, and conversation history growing until it hits the ceiling. This one is different, and in some ways worse, because it’s a cost you pay before any work happens.

For the model to call a tool, it has to know the tool exists. So every tool’s full definition — name, description, input schema, argument descriptions — is sent on every request. That’s a fixed prefix charge, and it scales with your integrations, not your usage. Anthropic’s documentation puts a number on it:

“A typical multiserver setup (GitHub, Slack, Sentry, Grafana, and Splunk) can consume ~55k tokens in definitions before Claude does any work.”

Five servers. 55,000 tokens. Every request. And that’s typical — the engineering team describes the tail case bluntly: “In cases where agents are connected to thousands of tools, they’ll need to process hundreds of thousands of tokens before reading a request.”

There’s a second cost that doesn’t show up on an invoice but shows up in your error rate. More tools makes the model worse at choosing:

“Claude’s ability to pick the right tool degrades once you exceed 30–50 available tools.”

So the naive approach — connect every MCP server you might conceivably need, hand the model the full catalog — degrades on both axes at once. It gets more expensive and less accurate as you add capability. That’s the trap worth engineering your way out of.

Lever 1: don’t load what you won’t call

The tool search tool is the direct answer, and the news since the November 2025 announcement is that it’s no longer an experiment: it is generally available on the Claude API, with no beta header.

The mechanism is a single flag. You still send every tool definition in the tools array on every request — the API needs them server-side — but you mark the optional ones defer_loading: true, and they stay out of the context window until Claude goes looking:

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=2048,
    messages=[{"role": "user", "content": "What is the weather in San Francisco?"}],
    tools=[
        {"type": "tool_search_tool_regex_20251119", "name": "tool_search_tool_regex"},
        {
            "name": "get_weather",
            "description": "Get the weather at a specific location",
            "input_schema": {
                "type": "object",
                "properties": {"location": {"type": "string"}},
                "required": ["location"],
            },
            "defer_loading": True,
        },
    ],
)

Claude sees only the search tool (about 500 tokens) plus whatever you left non-deferred. When it needs something, it searches, the API returns matching tools as tool_reference blocks, expands them into full definitions, and Claude calls them. Two search variants ship: tool_search_tool_regex_20251119, where Claude writes Python re.search() patterns, and tool_search_tool_bm25_20251119, where it uses natural-language queries. Both search names, descriptions, argument names, and argument descriptions.

The savings, from Anthropic’s docs and its engineering write-up respectively:

And because tool selection stops degrading when the model only sees a focused set, accuracy moves too. The engineering post reports Opus 4.5 going from 79.5% to 88.1%, and Opus 4 from 49% to 74%, on their tool-use evaluation.

Supported on Fable 5, Mythos 5, Opus 4.8, Opus 4.7, Opus 4.6, Sonnet 4.6, Opus 4.5, Sonnet 4.5, and Haiku 4.5. Opus 4.1 and earlier don’t have it.

The practical limits are generous: up to 10,000 deferred tools per request, each search returns up to 5 matches, regex patterns cap at 200 characters and BM25 queries at 500. One hard rule — at least one tool must stay non-deferred (normally the search tool itself), or you get a 400 with All tools cannot be deferred.

Anthropic is also refreshingly clear about when not to use it. Skip tool search if you have fewer than 10 tools, if every tool is used in every request, or if your definitions total under 100 tokens. It earns its keep at 10+ tools, definitions over 10k tokens, or when you’re aggregating multiple MCP servers.

The one lever that doesn’t fight your cache

Here’s the detail that makes tool search stand out across this whole series, and it’s buried in the docs where most readers won’t hit it.

Both previous levers have a cache cost. Context editing invalidates the cached prefix when it clears content — you eat a cache write, which is exactly why clear_at_least exists. Compaction runs an entire extra sampling pass that reads your whole window. Tool search does neither:

“Internally, the API excludes deferred tools from the system-prompt prefix. When Claude discovers a deferred tool through tool search, the API appends a tool_reference block inline in the conversation, then expands it into the full tool definition before passing it to Claude. The prefix is untouched, so prompt caching is preserved.”

That’s an architectural choice worth appreciating. Deferred definitions never enter the prefix, and discovered ones arrive inline in the conversation rather than being retro-fitted into the cached block. Your prompt cache keeps working exactly as before.

If you’re picking one thing from this series to try first, this is the cheapest experiment: it’s GA, it’s a boolean on your existing tool definitions, it doesn’t disturb your caching, and it gets more accurate as your toolset grows.

Lever 2: stop piping results through the model

Tool search fixes the definitions. It does nothing about the other half of the problem: tool results.

The default flow forces every byte of every result through the model. Anthropic’s worked example is a meeting transcript being copied from Google Drive to Salesforce — the model reads the transcript to receive it, then writes it back out to send it. “For a 2-hour sales meeting, that could mean processing an additional 50,000 tokens,” for a task where the model doesn’t need to read the content at all.

Programmatic tool calling breaks that pattern. Claude writes Python that calls your tools inside a code-execution container; results are processed there, and only the final output returns to the model. It’s also now GA, requiring code_execution_20260120 or later:

tools=[
    {"type": "code_execution_20260120", "name": "code_execution"},
    {
        "name": "query_database",
        "description": "Run a SQL query",
        "input_schema": {
            "type": "object",
            "properties": {"sql": {"type": "string"}},
            "required": ["sql"],
        },
        "allowed_callers": ["code_execution_20260120"],
    },
]

The docs’ illustration is checking budget compliance across 20 employees. Traditionally that’s 20 round trips, dragging thousands of expense line items through context. With programmatic calling, one script runs all 20 lookups, filters, and returns only the employees who went over — “shrinking what Claude needs to reason over from hundreds of kilobytes down to a handful of lines.”

Measured results, again from two sources:

• Docs: on agentic-search benchmarks (BrowseComp and DeepSearchQA), adding programmatic tool calling on top of basic search tools improved performance by an average of 11% while using 24% fewer input tokens.
• Engineering post: average usage on complex research tasks dropped from 43,588 to 27,297 tokens, a 37% reduction, with internal knowledge retrieval improving 25.6% to 28.5% and GIA benchmarks 46.5% to 51.2%.

Supported models include Fable 5, Mythos 5, Opus 4.8, 4.7, 4.6, Sonnet 5, Sonnet 4.6, and Sonnet 4.5.

The restriction that catches everyone

Now the caveat, and it deserves its own section because the framing of this entire topic sets people up to get it wrong.

The other constraints are smaller but worth knowing before you architect around the feature:

• Structured outputs are out. Tools with strict: true aren’t supported with programmatic calling.
• You can’t force it. tool_choice can’t compel programmatic calling of a specific tool, and disable_parallel_tool_use: true isn’t supported.
• Recursive schemas fail. A custom tool whose input_schema contains a recursive $ref can’t be enabled for programmatic calling — you get a 400 with Circular $ref detected. The same schema is fine for direct calling. Workaround: keep that tool direct-only, or unroll the recursion to a fixed depth.
• Strict reply formatting. When responding to pending programmatic tool calls, your message must contain only tool_result blocks — no text content, even after the results — and each result’s content must be a string or text blocks. Images and documents are rejected.
• No rate-limit discount. Each tool call from code execution counts as a separate invocation against the same limits as regular tool calls.

Lever 3: the architecture behind the 98.7% figure

If you’ve seen this topic discussed, you’ve probably seen one number: 150,000 tokens down to 2,000 — a 98.7% saving. It’s real, it’s from Anthropic’s engineering post, and it’s important to understand what produced it, because it is not a flag you can switch on.

That figure comes from a pattern: presenting MCP servers to the agent as code APIs on a filesystem, where each tool is a file and the agent discovers tools by exploring directories. The agent then writes code against them. Anthropic’s summary of why this works:

“Agents can load only the tools they need and process data in the execution environment before passing results back to the model.”

The benefits stack up beyond raw tokens:

• Progressive disclosure. “Models are great at navigating filesystems” — they read tool definitions on demand instead of all up front.
• Filtering before the model sees anything. Transform and filter in code, so the agent reads five rows instead of ten thousand.
• Real control flow. Loops, conditionals, and error handling as ordinary code rather than chains of individual tool calls.
• Privacy. Intermediate results stay in the execution environment by default, and PII can be tokenized so sensitive values never reach the model.
• State and reusable skills. Agents write intermediate results to files to resume later, and can persist working code as reusable functions.

Which lever, when

Three posts into this series, the toolkit has enough pieces to need a map. Picking by symptom:

They compose. A heavyweight agent might defer 200 tool definitions, orchestrate the noisy ones in code, clear spent results as it goes, and keep durable notes in memory — each lever aimed at a different part of the window.

The honest math

Two things to keep in proportion before you go tuning.

The headline percentages are best cases. 98.7% came from one specifically chosen workflow with a large document flowing through twice. “Over 85 percent” assumes a large catalog where the agent needs 3–5 tools. If you run eight tools and use most of them every request, tool search will cost you a search round trip and save you very little — which is precisely why Anthropic tells you not to bother below 10 tools.

Input tokens are the cheap side. Tool definitions are input, and input that sits in a stable prefix is cacheable at roughly a tenth of list price. Cutting 50k tokens of definitions that were being served from cache saves real money, but not list-price money — and on reasoning-heavy agents, output and thinking tokens often dominate the bill anyway. The strongest argument for tool search may not be the tokens at all: it’s that accuracy climbs when the model stops choosing among 200 tools. An agent that picks the right tool the first time saves a whole retry loop, and retries are billed in full.

That gap — between the token number a feature advertises and the dollar number that lands on your invoice — is a recurring theme in this series, and it’s big enough to deserve its own post. That’s the next one.

Verified on 2026-07-20 against Anthropic’s official documentation: tool search tool, programmatic tool calling, plus the engineering write-ups Code execution with MCP and Advanced tool use. Where the docs and the November 2025 announcement differ, the docs win — notably, both features are now generally available and the original advanced-tool-use-2025-11-20 beta header is no longer required. Benchmark figures are Anthropic’s own and reflect favorable scenarios; treat them as ceilings. This is the third post in a series on context engineering, after context editing and compaction. See our methodology for how we verify.