MCP definitions use 10.6× more input tokens until tool search defers them

A live catalogue of 831 MCP tools measures 127,440 tokens of definitions; deferring them cut one measured turn from 149,187 input tokens to 14,109. The commands to measure your own, and the five filed cases where deferral leaves the bill in place.

A connected MCP server costs nothing while its tools sit idle, and costs on every request, because the definitions travel with the request. MCP — Model Context Protocol — is the wire format an agent uses to discover and call tools on an external server. Its discovery call, tools/list, returns one object per tool: a name, a description, and a JSON Schema for the arguments. A client that keeps those objects in the request pays for all of them every turn, whether the model calls one or none.

Evidence status

Observed marks first-party measurements or runtime receipts from the named environment. Derived marks arithmetic calculated from cited inputs. Specified marks vendor or standards documentation. Implemented and deployed name code and live-state evidence, respectively. Reproduced means the stated procedure was rerun. Externally attested marks operator reports; those reports show that an experience occurred, not that it is universal.

A definition is a name, a sentence and a schema, and the schema is the part that grows

One live tool object, from POST https://miscsubjects.com/api/mcp with {"jsonrpc":"2.0","id":1,"method":"tools/list"}:

json24 lines1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  "name": "CF_AI_GATEWAY_LIST_LOGS",
  "description": "List Logs MCP: https://ai-gateway.mcp.cloudflare.com/sse [fn · cf_ai_gateway]",
  "inputSchema": {
    "type": "object",
    "properties": {
      "gateway_id": { "type": "string", "description": "The gateway ID." },
      "page": { "default": 1, "type": "integer" },
      "per_page": { "default": 20, "type": "integer" },
      "order_by": { "default": "created_at", "type": "string",
        "enum": ["created_at","provider","model","model_type","success",
                 "cached","cost","tokens_in","tokens_out","duration","feedback"] },
      "order_by_direction": { "default": "desc", "type": "string", "enum": ["asc","desc"] },
      "start_date": { "type": "string" },
      "end_date": { "type": "string" },
      "feedback": { "type": "number" },
      "success": { "type": "boolean" },
      "cached": { "type": "boolean" },
      "model": { "type": "string" },
      "provider": { "type": "string" }
    },
    "required": ["gateway_id"]
  }
}
Line 24, Column 1JSON

That object is 264 tokens by the o200k_base tokenizer: 11 for the name, 22 for the description, 231 for argument names, types, defaults and one enum of eleven strings.

A description is written once by a human and stays a sentence. A schema grows with the API behind it — every optional filter, enum member and nested object — and nothing prunes it. The MCP specification requires it: tools/list returns name, optional title, description and inputSchema per tool, so there is no conforming way to publish a tool without publishing its argument surface.

Across the whole 831-tool catalogue on 2026-07-26, names cost 4,064 tokens, descriptions 54,596, schemas 54,465. Level in aggregate, which is not the folklore. Split by size and the folklore returns:

Slice of the catalogue	Tools	Tokens	Share that is schema
Definitions under 300 tokens	800	109,856	39%
Definitions 300 tokens or more	31	17,584	67%
The 20 most expensive definitions	20	13,963	75%
The single most expensive, `CF_OBSERVABILITY_QUERY_WORKER_OBSERVABILITY`	1	1,803	95%

Cheap tools are mostly prose; expensive tools are almost entirely schema. A catalogue's bill is set by its handful of query-shaped tools, not its median row. An independent measurement on a different server found the same tail: G-Core's MCP server at GCORE_TOOLS=* advertises 741 tools for about 488,013 tokens, an average of 659 per tool, one tool alone at about 7,046 tokens of schema.

Measure it three ways, cheapest first

1. /context, in a running session. Breaks the window into system prompt, system tools, MCP tools, memory, skills and messages. Free, one second. Read the contradiction section before trusting a zero.

2. The usage field of any API response. Every Messages API response carries usage.input_tokens, usage.output_tokens and the cache counters. Send the same one-word prompt twice, with the servers attached and without, and subtract. The only method that measures what you are billed for.

3. A capture server, for what the client puts on the wire. A local HTTP server that speaks enough of the Messages API to answer, and logs every request:

bash

git clone https://github.com/redacted/claude-code-cloudflare-gateway
cd claude-code-cloudflare-gateway
node tools/capture-gateway.mjs      # listens on :8787, appends capture.jsonl

Line 3, Column 1Shell Script

It records n_tools, tool_names, system_chars, system_cache_control, metadata and the model per request, redacting authorization and x-api-key. Point the client at it twice, changing one variable:

bash

ANTHROPIC_BASE_URL=http://localhost:8787 ANTHROPIC_AUTH_TOKEN=x \
  ENABLE_TOOL_SEARCH=false claude -p "say ok"

ANTHROPIC_BASE_URL=http://localhost:8787 ANTHROPIC_AUTH_TOKEN=x \
  ENABLE_TOOL_SEARCH=true claude -p "say ok"

Line 5, Column 1Shell Script

Read the two tool counts out of the log:

bash

python3 -c "
import json
for line in open('capture.jsonl'):
    r = json.loads(line)
    if r.get('n_tools') is not None:
        print(r['model'], 'tools=', r['n_tools'])
"

Line 7, Column 1Shell Script

Two lines. On claude-cli 2.1.165 against that server on 2026-07-25: tools= 856 and tools= 9 — the nine being Agent, AskUserQuestion, Bash, Edit, Read, Skill, ToolSearch, Workflow, Write.

To price a catalogue without running the client, count the tokens the server publishes. The command behind the 831-tool figures above, good against any HTTP MCP server that answers tools/list:

bash

curl -s -X POST https://miscsubjects.com/api/mcp \
  -H "Authorization: Bearer $MCP_TOKEN" -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' -o tools.json

python3 -m venv /tmp/tokvenv && /tmp/tokvenv/bin/pip install tiktoken
/tmp/tokvenv/bin/python -c "
import json, tiktoken
enc = tiktoken.get_encoding('o200k_base')
t = json.load(open('tools.json'))['result']['tools']
tot = sum(len(enc.encode(json.dumps(x))) for x in t)
print('tools', len(t), 'tokens', tot, 'mean', round(tot/len(t), 1))
"

Line 12, Column 1Shell Script

Output on 2026-07-26: tools 831 tokens 127440 mean 153.4, from a 434,636-byte response. o200k_base is OpenAI's tokenizer, not Anthropic's — treat it as a close estimate and billed usage as the truth. They agree to about 12% here: 149,187 billed input tokens for 856 definitions plus a system prompt and a short user message is 174.3 tokens per definition against the tokenizer's 153.4.

Three configurations, same catalogue, same day

Same machine, same catalogue of 891 capabilities, same trivial prompt, @cf/moonshotai/kimi-k2.7-code through a Cloudflare AI Gateway, 2026-07-25. Tokens and cost read from the gateway's own log rows.

Configuration	Tool definitions in the request	Input tokens	Cost per turn
Every directory row projected as an MCP tool, definitions in context	856	149,187	$0.02852109
Same catalogue, `ENABLE_TOOL_SEARCH=true`	9, one of them `ToolSearch`	14,109	$0.00443075
No MCP server attached, the same 891 capabilities reached over HTTP	9 built-in tools	14,071	$0.00456265

149,187 input tokens is 74.6% of a 200,000-token window, spent before the user's sentence is read. Deferring the definitions cuts that 10.6-fold, 135,078 tokens a turn.

The third row decides architecture: tool search on is as cheap as having no MCP server at all — 14,109 against 14,071, a 0.3% difference — with every tool still reachable. The tools were never the cost. The definitions were.

The dollar column is the gateway's own accounting and is an estimate; the token counts are measured at both ends and the argument rests on them.

That 14,071-token row is still readable. Fetched 2026-07-26 from the AI Gateway logs REST endpoint (GET /accounts/<account_id>/ai-gateway/gateways/default/logs?per_page=3&order_by=created_at&order_by_direction=desc):

json

{"created_at":"2026-07-26T03:43:18.667Z","model":"@cf/moonshotai/kimi-k2.7-code",
 "metadata":{"via":"claude-code","shim":"api/aig","tools":9},
 "tokens_in":14071,"tokens_out":170,"cost":0.00456265,
 "usage_metadata":{"input_cached_tokens":12480}}

Line 4, Column 1JSON

metadata.tools is what the client sent: nine, not 856, with the same catalogue attached.

The attribution line was worth more than 12,000 cached tokens a turn

Claude Code prepends an attribution block — client version and prompt fingerprint — to the start of the system prompt. A prompt cache keys on an exact prefix, so a value that changes per request, at the front, means the prefix never matches and nothing before it is ever a hit. Anthropic's environment-variable reference: set CLAUDE_CODE_ATTRIBUTION_HEADER to 0 to omit the block, "Disabling it improves prompt-cache hit rates when routing through an LLM gateway. Caching on a direct connection to the Anthropic API is unaffected either way."

Measured on the rows above, cached input went from 64 tokens to 12,480 tokens per turn once the line was dropped — 88% of a 14,109-token turn arriving from cache instead of priced as fresh.

bash

export CLAUDE_CODE_ATTRIBUTION_HEADER=0

Line 1, Column 1Shell Script

Anthropic's gateway protocol reference adds the version detail and the right place to fix it: from v2.1.181 the block is stable for the lifetime of a conversation behind a custom base URL, and "If your gateway must reshape system content, set CLAUDE_CODE_ATTRIBUTION_HEADER=0 so Claude Code omits the block… omit it at the client rather than stripping or moving it in the gateway." Stripping it gateway-side breaks attribution downstream; omitting it at the client does not.

Deferred tool search: names stay, schemas arrive on request

Anthropic's documentation describes the mechanism: "When tool search is active, tool definitions are withheld from the context window. The agent receives a summary of available tools and searches for relevant ones when the task requires a capability not already loaded. Up to five of the most relevant tools are loaded into context by default." A discovered tool stays available for later turns; if compaction removes it, the model searches again.

The switch:

bash

export ENABLE_TOOL_SEARCH=true

Line 1, Column 1Shell Script

Permanently, in ~/.claude/settings.json:

json

{ "env": { "ENABLE_TOOL_SEARCH": "true", "CLAUDE_CODE_ATTRIBUTION_HEADER": "0" } }

Line 1, Column 1JSON

Every value the variable accepts:

Value	Behaviour
unset	Deferred by default — but loaded upfront when `ANTHROPIC_BASE_URL` points at a non-first-party host, or on Google Cloud's Agent Platform
`true`	Always defer, and send the beta header even through a proxy. Requests fail on proxies that do not support `tool_reference` blocks
`auto`	Load upfront if the definitions fit within 10% of the context window, defer the overflow
`auto:N`	Same with a custom percentage, e.g. `auto:5`
`false`	Load every definition upfront, every turn

Two costs come with it, both small. The search tool's own definition stays in the request — it is one of the nine measured above, and Anthropic's API reference is explicit that "At least one tool, normally the tool search tool itself, must stay non-deferred." And the first use of an unseen tool costs an extra round-trip; below roughly ten tools, loading everything upfront is faster.

The API-side mechanism differs from the client-side one in a way that matters if you are building a gateway. With defer_loading: true on the Messages API, "You still send every tool's full definition in the tools array on every request, including the deferred ones. The API needs them server-side to run the search." The saving there is context, not bytes. The capture above shows the client doing the other thing — sending nine definitions — because behind a non-first-party base URL Claude Code resolves the search itself. Both are called tool search. Only one shrinks what leaves your machine.

Five ways the definitions stay in the bill anyway

What still costs	Where it was observed	The report
First-party servers exempt from deferral	Claude Desktop, `anthropics/claude-code` issue 76372, 2026-07-10	With tool search active, third-party MCP tools defer to names only, but "three Desktop built-in servers load complete schemas upfront every session" — about 3,900 tokens with no opt-out, isolated by reading `message.usage` from session JSONL across 6 sessions
Servers invisible to the search index	Claude Code 2.1.114, `anthropics/claude-code` issue 57033, 2026-05-07	Servers added at claude.ai/settings/connectors show Connected in `/mcp`, yet "Any `ToolSearch` query that should match a claude.ai MCP tool returns zero results". Local `.mcp.json` and plugin servers index fine
Threshold computed from the wrong model	`hermes-agent` issue 57520, 2026-07-03	The auto-gate reads the configured default model, not the session model, so "the gate is scaled to the wrong window" — a 98,304-token local model gets a 25,600-token threshold derived from a 256K cloud model instead of 9,830, and takes the whole payload inline
A turn that silently completes empty	codex-cli 0.133.0, `openai/codex` issue 24536, 2026-05-26	"`codex exec` can silently finish with no assistant message when an explicitly configured MCP tool is deferred behind `tool_search`" — the server stays healthy and registered but is only reachable through deferral, and the harness accepts the empty turn
Lazy loading invalidating the prompt cache	Hacker News, 2026-03-01	"The main problem with this approach at the moment is it busts your prompt cache, because LLMs expect all tool definitions to be defined at the beginning of the context window"

The cache row cuts the other way for the deferred case. Anthropic's caching page puts tool definitions in the system-prompt layer, so the cache invalidates when the set of definitions changes between turns — but with deferred tools, "a server connecting, disconnecting, or changing its tool list only appends new content and doesn't disturb anything already cached", while with tools in the prefix "any change to them invalidates the cache". A gateway is named as one place where deferral is off and the prefix is therefore fragile: a stdio process exiting, an HTTP session expiring or an automatic reconnect invalidates the whole cached prefix with nobody touching a keyboard.

An operator who ran it and was not convinced, on Hacker News on 2026-03-15: "And no, the tool search function recently introduced by Anthropic does not completely solve this problem."

One harness reports zero tokens per tool. Others publish tables of tens of thousands

Zero, filed against Claude Code as issue 23228 on 2026-02-05: "When running the /context command to check token usage, the output includes a long list of all MCP tool definitions (28 in my case), each showing '0 tokens'."

Not zero, filed on 2026-03-01 with a per-server breakdown: "The main agent context burns 16.9k tokens (8.5% of 200k) loading 68 MCP tool schemas at session start. Most are never called by the main agent — they're used by subagents." That author's table attributes 6.0k to one server's 25 tools, 3.3k to another's 14. Two more, independently: 741 tools at about 488,013 tokens on a G-Core server, and 250-plus definitions across 9 servers at "~40,000-70,000 tokens of tool definitions loaded upfront".

Both can be true, and the mechanism is documented. /context reports what is in the context window, category by category. Deferred definitions are by construction not in the window — Anthropic's cost guidance: "MCP tool definitions are deferred by default, so only tool names enter context until Claude uses a specific tool." A per-tool row of 0 tokens is then accurate, and the residual cost lands under another heading. The tables of tens of thousands come from sessions where the definitions were not deferred — an older client, a false setting, a non-first-party base URL, alwaysLoad, an exempt built-in server — and from harnesses that count the catalogue rather than ask the client.

Which to trust for a decision: neither, over the usage field of your own responses. /context reports placement, not billing, and its zero is silent about the 3,900 tokens of exempt built-in schemas in issue 76372. A tokenizer table reports the size of a catalogue, not what your client chose to send — the capture above shows a client sending 9 of 856. Only usage.input_tokens, differenced across two otherwise identical runs, answers the question being asked.

One dissent earns its place, from Hacker News on 2026-05-30: "The idea that MCP tool definitions take up a certain number of tokens is laughable. That's an implementation detail of the agent harness." Correct about the protocol, beside the point about the invoice: the protocol mandates no loading strategy, and the client you are running has already picked one and is billing you for it.

The arithmetic at 200 turns a day

200 model turns in a working day, 30 days in a month. Substitute your own turn count; the multiplication is the same.

Configuration	Cost per turn	× 200 turns = per day	× 30 days = per month
856 definitions in every request	$0.02852109	$5.70	$171.13
`ENABLE_TOOL_SEARCH=true`	$0.00443075	$0.89	$26.58
No MCP server, capabilities over HTTP	$0.00456265	$0.91	$27.38

One environment variable is worth $4.82 a day and $144.54 a month on one machine, one catalogue, these rates. In tokens, which do not depend on anyone's pricing: 135,078 fewer input tokens per turn, 27,015,600 fewer per day.

Two effects the table does not price. The definitions occupied 74.6% of a 200,000-token window, so the ceiling on what a session can hold moves further than the invoice does. And tool-selection accuracy is documented to degrade "with more than 30-50 tools loaded at once" — a quality cost with no line item.

Five responses, ranked by what they cost you to adopt

1. Turn tool search on. One variable, no code, every tool still reachable, measured 10.6× fewer input tokens. Trade-off: an extra round-trip on first use of an unseen tool; unavailable behind a base URL that cannot forward tool_reference blocks; below ten tools it is slower than loading them.

2. Scope servers per project. Enable a server only in the repository that needs it. An operator on Hacker News, 2026-07-12: "I enable tools specific to each project only in that project, and have very very few in my global config. Like <5k tokens worth." Trade-off: manual, and it fails the way manual hygiene always fails — the day you forget.

3. Collapse many tools into few. Replace N tools with one or two that take a name and arguments and dispatch internally. From the operator who built it: "This basically takes your APIs, databases, and docs and compresses them into 2 MCP tools (~1,000 tokens) instead of N tools (100K+ tokens)." A minimal version of the same idea, reported at about 60 tokens: one bare tool with a one-line description that unlocks the rest when called. Trade-off: you have rebuilt tool search without the harness's search quality, and the model must learn your dispatch convention.

4. Take the catalogue out of the prompt entirely. Publish capabilities behind an HTTP contract the model reads on demand, keep only the built-in tools. Measured at 14,071 input tokens with 891 capabilities reachable — the same number as tool search, a different structure, because catalogue size is no longer a term in the per-turn equation and no host support is required. Trade-off: your capabilities are not MCP tools, so anything that consumes MCP does not see them. Dimension by dimension in Tool search versus a catalogue as data, the data layer in Tooling as data, the three exposures side by side in MCP as a projection.

5. Do nothing. Defensible at a small tool count: under about ten tools, upfront loading is faster and the search round-trip is pure overhead. At 150–200 tools, two reports show the limit: one one-word prompt produced a request with "prompt_tokens: 154,367"; in the other, roughly 200 tool schemas exceeded a 32k window so completely that "/compact succeeded in producing a summary, but the very next request still failed."

Symptom, cause, fix

Symptom	Cause	Fix
Input tokens in the tens of thousands before your first word	Every definition in the prefix, every turn	`ENABLE_TOOL_SEARCH=true`
Setting it changed nothing, tools still all loaded	`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` is set — it "keeps tool search off, and `ENABLE_TOOL_SEARCH` can't override it"	Unset it, or accept upfront loading
Request fails after enabling it, behind a proxy	The proxy does not forward `tool_reference` blocks; errors of the form "Unexpected value(s) for the `anthropic-beta` header" or "Extra inputs are not permitted"	Fix the proxy to pass the beta header through, or set `ENABLE_TOOL_SEARCH=false`
Deferred by default on a direct connection, upfront through a gateway	Deferral is off by default "when `ANTHROPIC_BASE_URL` points to a non-first-party host"	Set `ENABLE_TOOL_SEARCH=true` explicitly
Tool search finds nothing for a server that `/mcp` shows Connected	claude.ai-hosted connectors are not in the search index (issue 57033)	Add the server via local `.mcp.json` instead
A scripted run ends with no assistant message	The required tool was deferred and the harness accepted an empty turn (codex issue 24536)	Mark that server `alwaysLoad`, or pin it non-deferred
One server must never need a search step	Deferral applies to every server by default	`"alwaysLoad": true` on that server in `.mcp.json` — every one of its tools then loads at session start regardless of `ENABLE_TOOL_SEARCH`
Cached input near zero behind a gateway	The attribution block changes the prefix per request	`CLAUDE_CODE_ATTRIBUTION_HEADER=0` at the client, never stripped in the gateway
Cache misses mid-session for no visible reason	A server connected, disconnected or pushed a tool-list change while definitions sat in the prefix	Defer the tools, so a server change "only appends new content"
`/context` shows every MCP tool at 0 tokens	Deferred definitions are not in the window; `/context` reports placement, not billing	Difference `usage.input_tokens` across two runs instead
Tool search on and the bill barely moved	Built-in or `alwaysLoad` servers are exempt (issue 76372, about 3,900 tokens)	Audit with a capture server; `n_tools` in the log is the ground truth

The gateway that produced these log rows, and how the same client runs on a non-Anthropic model, is documented in Claude Code on Kimi, GLM or Grok through your own Cloudflare account.

The two lines that carry the measurement

bash

export ENABLE_TOOL_SEARCH=true
export CLAUDE_CODE_ATTRIBUTION_HEADER=0

Line 2, Column 1Shell Script

The first defers tool definitions until the model searches for one. The second stops a per-request block at the front of the system prompt from moving the prompt-cache key. Neither requires the MCP server to change.

References (34)

Claude Code environment variables — ENABLE_TOOL_SEARCH and CLAUDE_CODE_ATTRIBUTION_HEADER — Anthropic, Jul 26, 2026“Set to `0` to omit the attribution block (client version and prompt fingerprint) from the start of the system prompt. Disabling it improves prompt-cache hit rates when routing through an LLM gateway. Caching on a direct connection to the Anthropic API is unaffected either way”
Connect Claude Code to tools via MCP — scale with MCP tool search — Anthropic, Jul 26, 2026“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.”
How Claude Code uses prompt caching — what invalidates a cached prefix — Anthropic, Jul 26, 2026“Deferred tools, the default on supported models: a server connecting, disconnecting, or changing its tool list only appends new content and doesn’t disturb anything already cached. Tools loaded into the prefix: any change to them invalidates the cache. This happens when tool search is unavailable or disabled, such as on Google Cloud’s Agent Platform or with a custom ANTHROPIC_BASE_URL gateway.”
Gateway protocol reference — where to disable the attribution block — Anthropic, Jul 26, 2026“If your gateway must reshape system content, set `CLAUDE_CODE_ATTRIBUTION_HEADER=0` so Claude Code omits the block. Anthropic and the cloud providers’ Claude endpoints read the block for attribution, so omit it at the client rather than stripping or moving it in the gateway.”
Manage costs effectively — MCP tool definitions are deferred by default — Anthropic, Jul 26, 2026“MCP tool definitions are deferred by default, so only tool names enter context until Claude uses a specific tool. Run `/context` to see what’s consuming space.”
Debug your configuration — what /context actually reports — Anthropic, Jul 26, 2026“The `/context` command shows everything occupying the context window for the current session, broken down by category: system prompt, system tools, MCP tools, custom subagents with the source each loaded from, memory files, skills, and conversation messages.”
Scale to many tools with tool search — the mechanism and its break-even point — Anthropic, Jul 26, 2026“When tool search is active, tool definitions are withheld from the context window. The agent receives a summary of available tools and searches for relevant ones when the task requires a capability not already loaded. Up to five of the most relevant tools are loaded into context by default.”
Model Context Protocol specification — tools/list — Model Context Protocol, Jun 18, 2025“{ "name": "get_weather", "title": "Weather Information Provider", "description": "Get current weather information for a location", "inputSchema": { "type": "object", "properties": { "location": { "type": "string", "description": "City name or zip code" } }, "required": ["location"] } }”
Tool search tool — defer_loading controls context, not the request body — Anthropic, Jul 26, 2026“You still send every tool’s full definition in the `tools` array on every request, including the deferred ones. The API needs them server-side to run the search and expand `tool_reference` blocks.”
capture-gateway.mjs — the logging server behind these wire measurements — Jul 25, 2026“tools/capture-gateway.mjs — a local Anthropic-compatible server that logs every request, recording n_tools, tool_names, system_chars, system_cache_control and metadata, with authorization and x-api-key redacted”
tiktoken harness against a live MCP server: 741 tools, ~488,013 tokens — GitHub, Jul 11, 2026“with `GCORE_TOOLS=*` it advertises **741 tools / ~488,013 tokens** (659/tool) — that exceeds a 200K context window on its own, so the full config can’t actually be used with most models.”
/context shows 28 MCP tool definitions, each at 0 tokens — GitHub, Feb 5, 2026“When running the `/context` command to check token usage, the output includes a long list of all MCP tool definitions (28 in my case), each showing "0 tokens".”
16.9k tokens on 68 MCP tool schemas, broken down per server — GitHub, Mar 1, 2026“The main agent context burns **16.9k tokens (8.5% of 200k)** loading 68 MCP tool schemas at session start. Most are never called by the main agent — they’re used by subagents.”
9 MCP servers, 250+ definitions, 40-70k tokens on every message — GitHub, Jul 5, 2026“With 9 MCP servers connected (project-tools, supabase, agent-browser, chrome-devtools, playwright, memory, context7, sequential-thinking, fetch), this results in ~40,000-70,000 tokens of tool definitions loaded upfront”
Built-in servers load full schemas despite tool search — ~3.9k tokens, no opt-out — GitHub, Jul 10, 2026“With tool search active (`ENABLE_TOOL_SEARCH` unset), third-party MCP tools correctly defer to names-only. But three Desktop built-in servers load complete schemas upfront every session”
ToolSearch does not index claude.ai-hosted servers — GitHub, May 7, 2026“the `ToolSearch` deferred-tool discovery mechanism does NOT include them in its index. Any `ToolSearch` query that should match a claude.ai MCP tool returns zero results”
A deferred tool can end a scripted run with no assistant message — GitHub, May 26, 2026“`codex exec` can silently finish with no assistant message when an explicitly configured MCP tool is deferred behind `tool_search`.”
The deferral threshold is computed from the wrong model — GitHub, Jul 3, 2026“For any session running a model *other than* the configured default (e.g. `--model qwen3.6-27b --provider llamacpp`, or a model switched via `/model` in the TUI), the gate is scaled to the wrong window.”
Loading tools lazily busts the prompt cache — Hacker News, Mar 1, 2026“The main problem with this approach at the moment is it busts your prompt cache, because LLMs expect all tool definitions to be defined at the beginning of the context window.”
A first-hand verdict: tool search does not completely solve it — Hacker News, Mar 15, 2026“And no, the tool search function recently introduced by Anthropic does not completely solve this problem.”
The dissent: token cost is a harness detail, not a protocol property — Hacker News, May 30, 2026“The idea that MCP tool definitions take up a certain number of tokens is laughable. That’s an implementation detail of the agent harness.”
The positive report: deferral retired the context-bloat complaint — Hacker News, May 30, 2026“Because Claude Code only loads the tools it needs now, so context bloat is pretty much solved for MCPs.”
Per-project scoping keeps a global tool surface under 5k tokens — Hacker News, Jul 12, 2026“I enable tools specific to each project only in that project, and have very very few in my global config. Like <5k tokens worth.”
Collapsing an API into two MCP tools: 100K+ tokens down to ~1,000 — Hacker News, Apr 2, 2026“This basically takes your APIs, databases, and docs and compresses them into 2 MCP tools (~1,000 tokens) instead of N tools (100K+ tokens). Claude was burning tokens (and a lot of them for me) on just tool definitions.”
A hand-rolled gate tool at about 60 tokens — Hacker News, Apr 10, 2026“That first tool consumes only about 60 tokens. As long as the LLM doesn’t need the tools, it takes almost no space.”
A unified-API vendor measured 50,000+ tokens before the first user message — Hacker News, Mar 16, 2026“We built a unified API with a large surface area and ran into a problem when building our MCP server: tool definitions alone burned 50,000+ tokens before the agent touched a single user message.”
One popular server named at about 50k tokens — Hacker News, Nov 17, 2025“Right now loading GitHub MCP takes something like 50k tokens.”
A one-word prompt that cost 154,367 input tokens — GitHub, Jul 18, 2026“A one-word prompt ("Reply with exactly one word: pong") produced a request with `prompt_tokens: 154,367`”
Schema overhead that /compact cannot recover — GitHub, Jul 19, 2026“`/compact` succeeded in producing a summary, but the **very next request still failed** — the non-compactable overhead (system prompt + ruflo tool schemas + plugin agent/skill listings) alone exceeded the limit.”
First-party: 831 published tool definitions, 127,440 tokens — Jul 26, 2026“tools 831 tokens 127440 mean 153.4 — from a tools/list response of 434,636 bytes; names 4,064 tokens, descriptions 54,596, schemas 54,465”
First-party: one real definition, 264 tokens, and where the tokens sit — Jul 26, 2026“CF_AI_GATEWAY_LIST_LOGS = 264 tokens: 11 name, 22 description, 231 schema. Across the catalogue, the 20 most expensive definitions are 13,963 tokens and 75% schema; the single most expensive, CF_OBSERVABILITY_QUERY_WORKER_OBSERVABILITY, is 1,803 tokens and 95% schema.”
First-party: a gateway log row, nine tools, 14,071 input tokens — Jul 26, 2026“{"created_at":"2026-07-26T03:43:18.667Z","model":"@cf/moonshotai/kimi-k2.7-code","metadata":{"via":"claude-code","shim":"api/aig","tools":9},"tokens_in":14071,"tokens_out":170,"cost":0.00456265,"usage_metadata":{"input_cached_tokens":12480}}”
First-party: 856 definitions become 9 on the wire — Jul 25, 2026“ENABLE_TOOL_SEARCH=false tools=856 | ENABLE_TOOL_SEARCH=true tools=9 [‘Agent’,‘AskUserQuestion’,‘Bash’,‘Edit’,‘Read’,‘Skill’,‘ToolSearch’,‘Workflow’,‘Write’]”
First-party: three configurations priced from gateway log rows — Jul 25, 2026“856 definitions 149,187 input / $0.02852109 · tool search on 14,109 / $0.00443075 · no MCP server, 891 capabilities over HTTP 14,071 / $0.00456265”

The system

Messaging

Ads and leads

Devices

Industries

Explore

MCP definitions use 10.6× more input tokens until tool search defers them

Evidence status

A definition is a name, a sentence and a schema, and the schema is the part that grows

Measure it three ways, cheapest first

Three configurations, same catalogue, same day

The attribution line was worth more than 12,000 cached tokens a turn

Deferred tool search: names stay, schemas arrive on request

Five ways the definitions stay in the bill anyway

One harness reports zero tokens per tool. Others publish tables of tens of thousands

The arithmetic at 200 turns a day

Five responses, ranked by what they cost you to adopt

Symptom, cause, fix