Weekly field note
Fifty Tool Definitions Cost 10,000 to 20,000 Tokens Before Your Agent Reads Anything
Published November 16, 2026
What the MCP specification, Claude Code and two Anthropic engineering posts document about tool-context cost, and a five-step audit for deciding which tools load upfront, which load on search, and which run inside code

*Image: 2023 Hub USB 2.0 by Jacek Halicki, licensed under CC BY-SA 4.0.*
A five-server setup in Anthropic's tool-search write-up totals 58 tools and about 55,000 tokens of definitions: GitHub at 35 tools and roughly 26,000 tokens, Slack at 11 tools and 21,000, Sentry and Grafana at 5 tools and 3,000 each, Splunk at 2 tools and 2,000. The same post puts Jira at about 17,000 tokens on its own, and reports that tool definitions at Anthropic have consumed 134,000 tokens before optimization. Every one of those tokens occupies context on every turn, whether or not a tool is called.
The catalog shares one context window with the system prompt, the message history and every tool result. Claude Code's tool-search documentation sizes 50 tools at 10,000 to 20,000 tokens and states that tool selection accuracy degrades with more than 30 to 50 tools loaded at once. So a working agent has two costs attached to its tool surface: window space on every turn, and a documented drop in choosing the right tool.
Each tool in that surface gets a placement decision. It can load upfront on every request, load on demand behind a search, or exist as code the agent calls from an execution environment. The vendor documentation covers all three placements, along with the conditions where each one loses.
What the protocol fixes and what the client decides
The MCP specification for tools defines a tool as a name, an optional title, a description, an inputSchema, an optional outputSchema and optional annotations. Clients discover tools with a tools/list request, and that request supports pagination through a cursor with a nextCursor in the response, so a catalog can be handed over in more than one page. Servers that declare listChanged are expected to send a notification when the list changes.
The specification covers discovery and invocation. It does not say how many definitions a client places in a model's context, or when. That belongs to the client, and the client's defaults set the per-request bill. The same spec page notes that clients must treat tool annotations as untrusted unless they come from trusted servers, which matters once placement decisions start relying on a hint a server wrote about itself.
Three placements
Upfront, on every request. This is what most MCP clients do, and Anthropic's code-execution post describes the shape: definitions sent directly to the model, exposed through ordinary tool calling. The Claude Code documentation gives the boundary where it still wins, listing fewer than about 10 tools with definitions that fit comfortably in the window as the case where loading everything upfront is typically faster than searching.
Deferred behind a search. The API version works by sending all definitions to the API and marking the deferrable ones with defer_loading: true. Claude then sees the search tool plus any tools marked defer_loading: false. A search returns references to matching tools, and only those expand into full definitions. Anthropic's measured comparison on the same page: about 77,000 tokens consumed before work begins under the traditional approach, against about 8,700 with the search tool in place, which the post reports as an 85 percent reduction, though its own two figures work out closer to 89 percent. Its internal MCP evaluations moved from 49 to 74 percent on Opus 4 and from 79.5 to 88.1 percent on Opus 4.5 with the feature enabled.
Claude Code turns the same mechanism on by default and adds the operational details an operator has to know:
- A search loads up to five of the most relevant tools, and they stay available until the SDK compacts the messages where the agent found them. After compaction the agent searches again.
- Core built-in tools such as
Bash,ReadandEditload upfront and are excluded from the deferral threshold. ENABLE_TOOL_SEARCHcan be left unset or set totrue,auto,auto:Norfalse. Unset ortrue, tool search is on and definitions are deferred from the start. Underauto, definitions load upfront until the deferrable ones reach 10 percent of the model's context window, andauto:5moves that trigger to 5 percent.- An individual MCP tool can be exempted with
alwaysLoad. - Deferral falls back to upfront loading on models earlier than Opus 4 and Sonnet 4, on models on the SDK's unsupported-model list, on earlier Agent Platform models and on Microsoft Foundry deployments hosted on Azure. The last two reject it in the serving stack, and
ENABLE_TOOL_SEARCHcannot override that. SettingCLAUDE_CODE_DISABLE_EXPERIMENTAL_BETASalso keeps tool search off, unless an organization keeps it on through managed settings on Claude Code v2.1.227 or later. A session that receives the HIPAA configuration runs with it off, and neither the environment variable nor managed settings can turn it back on.
Inside code. The code-execution post describes one approach that presents each MCP server as a directory of TypeScript functions, so the agent lists servers/, reads the one tool file it needs, and calls it. Its discount comes from two places. The first is the smaller definition surface: the post reports 150,000 tokens dropping to 2,000 in its filesystem-discovery example, a 98.7 percent reduction. The second is processing results in the environment, where a ten-thousand-row sheet is filtered in code and the model sees five rows, a saving the post shows without putting a number on it. The post states the cost plainly, since running agent-generated code needs a sandbox, resource limits and monitoring. Cloudflare's Code Mode post describes the same direction independently, reporting that agents handled many more tools, and more complex ones, when the tools arrived as a TypeScript API, with the benefit concentrated in tasks that chain several calls.
The API post documents a second mechanism, Programmatic Tool Calling. Tools opt in through an allowed_callers field naming the code execution tool, and Claude writes a Python script that runs in the API's Code Execution tool, a sandboxed environment. Tool results go to the script instead of the model, and Claude sees only the final output. The post reports average usage dropping from 43,588 to 27,297 tokens, a 37 percent reduction on complex research tasks, and lists three or more dependent tool calls, large datasets where only aggregates are needed, and filtering or transforming results before Claude sees them among the cases where it is most beneficial.
A five-step audit
The steps below are my assembly of those documented parts. The bucket names, the order, the threshold advice and the measurement procedures are mine; the documented facts they rest on are linked where they appear, and the larger extensions are flagged as they come up.
- Count the surface you ship. The token-counting endpoint accepts the same structured inputs as a message request, tools included, and returns input tokens. It returns an
invalid_request_errorfor server tools such as code execution and tool search, for the MCP connector, and for image or document blocks with aurlorfilesource, which covers several configurations this audit looks at. For requests that use server tools or MCP servers, read the token count in theusageobject of the Messages API response instead. Whichever count applies, send the real request twice, once with the tools and once without them, and the difference is the catalog's share of the window. Doing it per server rather than once for the whole set is my addition, because the bucketing in step 2 and the audit record that follows are both per server.
- Bucket servers by how often a session uses them. Read a week of transcripts and, for each server, record the fraction of sessions that called at least one of its tools. Three buckets follow. Servers used in most sessions load upfront. Servers used in some or few sessions are deferred. Servers whose calls arrive mostly inside a chain of dependent calls, or return large results the agent only needs summarized, go to code, a criterion taken from the API post's list of where programmatic tool calling is most beneficial. Anthropic's guidance lists more than 10,000 tokens of definitions, 10 or more tools and observed selection errors as reasons to search. It names three separate conditions where search is less beneficial: a library of fewer than 10 tools, all tools used frequently in every session, and compact definitions. The second of those is the one that supports bucketing by frequency. Bucketing by server is my choice, because the API's MCP toolset configuration sets its default per server; the last section covers the server this does not fit.
- Set the deferral threshold on purpose. Leaving
ENABLE_TOOL_SEARCHunset defers definitions from the start.autowaits until deferrable definitions reach 10 percent of the window, andauto:5activates at 5 percent, which suits a surface that has grown past its budget. The value covers the whole session: underauto, the SDK counts every deferrable definition, from any server, toward one combined threshold. Each value is a choice, so write it down with the session configuration it applies to. The per-server buckets from step 2 are set elsewhere. In the API, anmcp_toolsetentry withdefault_configset todefer_loading: truedefers a server, and a per-tooldefer_loading: falsekeeps a tool loaded; in Claude Code,alwaysLoadexempts an MCP tool from deferral. Tools in the code bucket opt in throughallowed_callers. Before rollout, check the platform against the fallback list in the tool-search section above. In any of those cases, every definition loads into context, whatever the intended setting was.
- Measure selection separately from token count. Build a small labelled set of tasks with a known correct tool, then run it before and after the change. This test is my suggestion; the vendor pages report accuracy figures without publishing a procedure. A surface that got cheaper and picks the wrong tool more often is a worse surface.
- Recheck caching, latency and compaction. Deferred tools stay out of the initial prompt, so the system prompt and the core definitions remain cacheable, as the API post notes. A search adds a round-trip before the tool runs, which the Claude Code documentation describes qualitatively and does not quantify. Compaction forces a fresh search for a tool the agent had already found, so a long session pays for discovery more than once.
A worked audit
The output below is invented to show the shape of the record. It is not a measurement from a real system.
tool surface audit 2026-11-16 project: support-agent
server tools def_tokens sessions_used bucket
github 35 26,000 0.18 deferred
slack 11 21,000 0.91 upfront
jira 9 17,000 0.06 deferred
sentry 5 3,000 0.44 deferred
grafana 5 3,000 0.31 deferred
splunk 2 2,000 0.03 code
catalog total 67 72,000
upfront after change 21,000 (slack; built-ins not counted)
search tool overhead 500
The per-server token figures and five of the six tool counts are copied from the vendor post; the Jira count, the session frequencies and the call patterns below are invented. sessions_used is the fraction of sampled sessions that called at least one tool from that server, and it separates upfront from the other two buckets. def_tokens is the token delta from step 1 for that server alone. The Slack entry shows why frequency beats size in this scheme: it holds the largest per-tool definitions in the set and still earns placement upfront, because nine sessions in ten call it. Jira and Splunk are both rare, so the call pattern from step 2 decides between them. In this sample, Jira's calls are single ticket lookups, so it is deferred, while Splunk's arrive inside log-search sequences whose raw results the agent only needs to count, so its tools go to code.
Where the documentation stops
The numbers come from the vendors. The 134,000-token figure carries no configuration, the 85 percent reduction compares one specific setup against another, and the accuracy figures are described as internal testing. They are worth reading as the direction and the order of magnitude, and they cannot tell you what your own catalog costs or how your own traffic responds.
Token cost per tool is not a constant. GitHub's 35 tools at about 26,000 tokens work out to roughly 740 tokens each, while Slack's 11 tools at 21,000 work out to about 1,900. Those are my divisions of the post's own figures, and they argue for a per-server budget instead of a per-tool count. My inference, which none of the pages tests, is that a server whose descriptions carry usage rules, enumerations and examples is the expensive kind. Trimming those descriptions has a price. Tool search matches against names and descriptions, and the API post says clear, descriptive definitions improve discovery accuracy; it also reports that tool use examples add tokens yet raised accuracy on complex parameter handling from 72 to 90 percent.
Search needs names that describe the job. The failure the API post names is wrong tool selection and incorrect parameters, especially between tools with similar names such as notification-send-user and notification-send-channel. A search matches on names and descriptions. My inference, which none of the pages tests, is that two near-identical names keep the same confusion after deferral unless their descriptions clearly separate them. Renaming one of them is my suggested fix; the pages recommend descriptive names and descriptions without addressing collisions directly.
The cost of the code placement depends on the mechanism. With code execution over MCP, the sandbox is yours to run: the post that documents it lists a secure execution environment, resource limits and monitoring as prerequisites, along with the operational overhead and security considerations that direct tool calls avoid. Programmatic Tool Calling runs in the API's Code Execution tool, so the sandbox comes with the API, and the overhead the API post names is the added code execution step. In both, filtering results is one of the places the saving comes from, so a workflow that makes one call and reads one short response has little to gain there. The API post lists simple single-tool invocations and quick lookups with small responses among the cases where programmatic tool calling is less beneficial.
The case the steps leave open
A server that holds both kinds of tool is where the per-server bucketing in step 2 runs out, and the configuration that handles it splits by tool instead. A server with one frequent lookup and forty rare write tools keeps the lookup loaded and defers the rest: Anthropic's MCP toolset configuration defers a whole server by default while naming individual tools to load upfront. Where a tool is both frequent and expensive, measure that tool the way step 1 measures a server, and let the delta decide. That is a judgement from the placement logic rather than a documented rule, and it holds while the definition cost of the frequent tool stays small relative to the context window. Your own measurement is the only one that describes your configuration, so take it before the change and again after.