{"slug":"mcp-tool-search-cost","verification":{"valid":false,"broken_at":0,"reason":"prev mismatch"},"count":34,"sources":[{"id":"s1","type":"publisher_documentation","url":"https://code.claude.com/docs/en/env-vars","title":"Claude Code environment variables — ENABLE_TOOL_SEARCH and CLAUDE_CODE_ATTRIBUTION_HEADER","quote":"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","summary":"The authoritative list of both variables this page turns on, including every accepted value of ENABLE_TOOL_SEARCH (true / auto / auto:N / false) and the note that CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS overrides it. Positive: it documents the fix.","publisher":"Anthropic","date":"2026-07-26","claim_ids":["c15","c5","c8"],"author":""},{"id":"s2","type":"publisher_documentation","url":"https://code.claude.com/docs/en/mcp","title":"Connect Claude Code to tools via MCP — scale with MCP tool search","quote":"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.","summary":"What deferral does, the alwaysLoad escape hatch that exempts a server from it, the 2KB truncation of tool descriptions, and the statement that deferral is off by default behind a non-first-party ANTHROPIC_BASE_URL. Positive on the mechanism, and the source of two symptom-table fixes.","publisher":"Anthropic","date":"2026-07-26","claim_ids":["c15","c7","c8"],"author":""},{"id":"s3","type":"publisher_documentation","url":"https://code.claude.com/docs/en/prompt-caching","title":"How Claude Code uses prompt caching — what invalidates a cached prefix","quote":"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.","summary":"The second-order cost: with definitions in the prefix, an MCP server reconnecting mid-session throws away the whole cached prefix. Negative for the default configuration, positive for deferral.","publisher":"Anthropic","date":"2026-07-26","claim_ids":["c9"],"author":""},{"id":"s4","type":"publisher_documentation","url":"https://code.claude.com/docs/en/llm-gateway-protocol","title":"Gateway protocol reference — where to disable the attribution block","quote":"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.","summary":"Says the fix belongs at the client, not in the gateway, and dates the change: from v2.1.181 the block is stable for the life of a conversation behind a custom base URL. Explains why the 64-to-12,480 cached-token jump happened on earlier clients.","publisher":"Anthropic","date":"2026-07-26","claim_ids":["c6"],"author":""},{"id":"s5","type":"publisher_documentation","url":"https://code.claude.com/docs/en/costs","title":"Manage costs effectively — MCP tool definitions are deferred by default","quote":"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.","summary":"The sentence that reconciles the contradiction: deferred definitions are not in the window, so a per-tool row of 0 tokens in /context is accurate rather than a bug.","publisher":"Anthropic","date":"2026-07-26","claim_ids":["c13"],"author":""},{"id":"s6","type":"publisher_documentation","url":"https://code.claude.com/docs/en/debug-your-config","title":"Debug your configuration — what /context actually reports","quote":"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.","summary":"Establishes that /context reports placement in the window, not billing — the distinction that decides which measurement to trust for a spending decision.","publisher":"Anthropic","date":"2026-07-26","claim_ids":["c13"],"author":""},{"id":"s7","type":"publisher_documentation","url":"https://code.claude.com/docs/en/agent-sdk/tool-search","title":"Scale to many tools with tool search — the mechanism and its break-even point","quote":"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.","summary":"The vendor description of deferral, the two costs (an extra round-trip, faster to load everything under ~10 tools), and two numbers reused here: 50 tools can use 10-20K tokens, and selection accuracy degrades beyond 30-50 loaded tools.","publisher":"Anthropic","date":"2026-07-26","claim_ids":["c14","c7"],"author":""},{"id":"s8","type":"specification","url":"https://modelcontextprotocol.io/specification/2025-06-18/server/tools","title":"Model Context Protocol specification — tools/list","quote":"{ \"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\"] } }","summary":"The wire shape every MCP server must return: name, optional title, description and inputSchema per tool. Establishes that the JSON Schema is not optional, which is why the argument surface is what grows.","publisher":"Model Context Protocol","date":"2025-06-18","claim_ids":["c1"],"author":""},{"id":"s9","type":"specification","url":"https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool","title":"Tool search tool — defer_loading controls context, not the request body","quote":"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.","summary":"The API-side reference. Two things a gateway builder needs: at least one tool (normally the search tool) must stay non-deferred, and server-side deferral saves context but not wire bytes — unlike the client-side behaviour measured here.","publisher":"Anthropic","date":"2026-07-26","claim_ids":["c10","c11"],"author":""},{"id":"s10","type":"repository","url":"https://github.com/massoumicyrus/claude-code-cloudflare-gateway","title":"capture-gateway.mjs — the logging server behind these wire measurements","quote":"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","summary":"MIT repository holding the capture harness and a 21-check contract test, so the 856-versus-9 tool count can be re-derived on any client version by anyone.","date":"2026-07-25","claim_ids":["c12","c4"],"author":"","publisher":""},{"id":"s11","type":"independent_measurement","url":"https://github.com/G-Core/gcore-mcp-server/issues/14","title":"tiktoken harness against a live MCP server: 741 tools, ~488,013 tokens","quote":"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.","summary":"An independent tokenizer run against a vendor MCP server listing, with a per-tool average and one tool measured at ~7,046 tokens of schema. Negative on definitions-in-context at scale, and the closest external replication of the method published here.","author":"lCrazyblindl","publisher":"GitHub","date":"2026-07-11","claim_ids":["c14","c2"]},{"id":"s12","type":"github","url":"https://github.com/anthropics/claude-code/issues/23228","title":"/context shows 28 MCP tool definitions, each at 0 tokens","quote":"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\".","summary":"The observation that contradicts every published token table. Filed as a cosmetic request; used here as the harness’s own accounting disagreeing with manual estimates.","author":"oneGunk","publisher":"GitHub","date":"2026-02-05","claim_ids":["c13"]},{"id":"s13","type":"github","url":"https://github.com/yonatangross/orchestkit/issues/885","title":"16.9k tokens on 68 MCP tool schemas, broken down per server","quote":"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.","summary":"The most rigorous per-server table found: 25 tools at ~6.0k, 14 at ~3.3k, and so on, with ENABLE_TOOL_SEARCH noted as available and unused. Negative, and the other half of the published contradiction.","author":"yonatangross","publisher":"GitHub","date":"2026-03-01","claim_ids":["c13"]},{"id":"s14","type":"github","url":"https://github.com/anomalyco/opencode/issues/35376","title":"9 MCP servers, 250+ definitions, 40-70k tokens on every message","quote":"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","summary":"A third independent count in the same range, from an ordinary nine-server setup rather than a large catalogue. Negative: the definitions are a per-message tax.","author":"jijoyo","publisher":"GitHub","date":"2026-07-05","claim_ids":["c13","c2"]},{"id":"s15","type":"github","url":"https://github.com/anthropics/claude-code/issues/76372","title":"Built-in servers load full schemas despite tool search — ~3.9k tokens, no opt-out","quote":"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","summary":"Measured from session JSONL message.usage across 6 sessions and 3 projects. Negative on deferral as a complete fix, and the reason a zero in /context does not mean a zero on the invoice.","author":"NAJEMWEHBE","publisher":"GitHub","date":"2026-07-10","claim_ids":["c11","c13"]},{"id":"s16","type":"github","url":"https://github.com/anthropics/claude-code/issues/57033","title":"ToolSearch does not index claude.ai-hosted servers","quote":"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","summary":"On Claude Code 2.1.114, connectors added at claude.ai show Connected in /mcp yet are invisible to deferred discovery, while local .mcp.json and plugin servers index fine. Negative: a deferred tool nobody can find is a missing tool.","author":"brasscats","publisher":"GitHub","date":"2026-05-07","claim_ids":["c11"]},{"id":"s17","type":"github","url":"https://github.com/openai/codex/issues/24536","title":"A deferred tool can end a scripted run with no assistant message","quote":"`codex exec` can silently finish with no assistant message when an explicitly configured MCP tool is deferred behind `tool_search`.","summary":"codex-cli 0.133.0 with a 90-tool GitHub connector: the required server stays healthy and registered but is only reachable through deferral, and the harness accepts the empty turn. Negative: the fix for tool count introduced a silent-failure mode.","author":"yanxiyue","publisher":"GitHub","date":"2026-05-26","claim_ids":["c11"]},{"id":"s18","type":"github","url":"https://github.com/NousResearch/hermes-agent/issues/57520","title":"The deferral threshold is computed from the wrong model","quote":"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.","summary":"Traces the auto-gate to a function reading config rather than the session model: 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 payload inline. Negative, with the offending code quoted.","author":"JT-III","publisher":"GitHub","date":"2026-07-03","claim_ids":["c11"]},{"id":"s19","type":"hn","url":"https://news.ycombinator.com/item?id=47209810","title":"Loading tools lazily busts the prompt cache","quote":"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.","summary":"The second-order cost of per-skill lazy loading, from an operator: input tokens are the main cost driver, so cache invalidation can undo the saving. Negative on naive lazy loading, and the reason the vendor’s append-only deferral matters.","author":"sophiabits","publisher":"Hacker News","date":"2026-03-01","claim_ids":["c11","c9"]},{"id":"s20","type":"hn","url":"https://news.ycombinator.com/item?id=47392361","title":"A first-hand verdict: tool search does not completely solve it","quote":"And no, the tool search function recently introduced by Anthropic does not completely solve this problem.","summary":"An operator who pays the definition cost for servers he never invokes on a turn, pre-empting the obvious rebuttal. Negative on deferred tools as a total fix.","author":"cheema33","publisher":"Hacker News","date":"2026-03-15","claim_ids":["c11","c16"]},{"id":"s21","type":"hn","url":"https://news.ycombinator.com/item?id=48331540","title":"The dissent: token cost is a harness detail, not a protocol property","quote":"The idea that MCP tool definitions take up a certain number of tokens is laughable. That’s an implementation detail of the agent harness.","summary":"The counterweight to every measurement here. Correct about the specification, which mandates no loading strategy; beside the point about the invoice, since the client has already chosen one.","author":"827a","publisher":"Hacker News","date":"2026-05-30","claim_ids":["c16"]},{"id":"s22","type":"hn","url":"https://news.ycombinator.com/item?id=48332962","title":"The positive report: deferral retired the context-bloat complaint","quote":"Because Claude Code only loads the tools it needs now, so context bloat is pretty much solved for MCPs.","summary":"Points at the source article retracting its first problem after deferred loading shipped, citing an 85%+ context reduction. Positive on tool search, and it disagrees directly with the operator in s20.","author":"didibus","publisher":"Hacker News","date":"2026-05-30","claim_ids":["c16","c7"]},{"id":"s23","type":"hn","url":"https://news.ycombinator.com/item?id=48885036","title":"Per-project scoping keeps a global tool surface under 5k tokens","quote":"I enable tools specific to each project only in that project, and have very very few in my global config. Like <5k tokens worth.","summary":"The manual alternative, working in practice for one operator. Positive on scoping, and the source of the second ranked response here.","author":"mh-","publisher":"Hacker News","date":"2026-07-12","claim_ids":["c17"]},{"id":"s24","type":"hn","url":"https://news.ycombinator.com/item?id=47614267","title":"Collapsing an API into two MCP tools: 100K+ tokens down to ~1,000","quote":"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.","summary":"An operator who hit six-figure token counts in definitions alone and built a two-tool dispatch layer whose index holds signatures rather than data. Positive on the collapse, negative on the status quo.","author":"codelitt","publisher":"Hacker News","date":"2026-04-02","claim_ids":["c17"]},{"id":"s25","type":"hn","url":"https://news.ycombinator.com/item?id=47719249","title":"A hand-rolled gate tool at about 60 tokens","quote":"That first tool consumes only about 60 tokens. As long as the LLM doesn’t need the tools, it takes almost no space.","summary":"The minimum viable version of deferral: one bare tool with a one-line description that unlocks the full set on call, plus a way back. Positive, and a concrete floor price for a dispatch surface.","author":"BeetleB","publisher":"Hacker News","date":"2026-04-10","claim_ids":["c17"]},{"id":"s26","type":"hn","url":"https://news.ycombinator.com/item?id=47400262","title":"A unified-API vendor measured 50,000+ tokens before the first user message","quote":"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.","summary":"Vendor-side measurement, replaced with a CLI at ~80 tokens of system prompt plus --help discovery, citing a 75-run comparison at 4-32x token overhead for MCP. Negative on the token cost, honest about where CLIs lose.","author":"gertjandewilde","publisher":"Hacker News","date":"2026-03-16","claim_ids":["c2"]},{"id":"s27","type":"hn","url":"https://news.ycombinator.com/item?id=45955033","title":"One popular server named at about 50k tokens","quote":"Right now loading GitHub MCP takes something like 50k tokens.","summary":"A named, widely-installed server with a number attached, from an operator who wants progressive reveal instead. Negative, and useful because most readers have that exact server connected.","author":"moltar","publisher":"Hacker News","date":"2025-11-17","claim_ids":["c2"]},{"id":"s28","type":"github","url":"https://github.com/nimbalyst/nimbalyst/issues/914","title":"A one-word prompt that cost 154,367 input tokens","quote":"A one-word prompt (\"Reply with exactly one word: pong\") produced a request with `prompt_tokens: 154,367`","summary":"150 MCP definitions plus a skills catalogue made a local 35B model unusable: rejected at 131k context, and 21m22s to prefill at 262k for a one-word reply. Negative, and the strongest case against doing nothing.","author":"Eventlessdrop","publisher":"GitHub","date":"2026-07-18","claim_ids":["c18"]},{"id":"s29","type":"github","url":"https://github.com/ruvnet/ruflo/issues/2726","title":"Schema overhead that /compact cannot recover","quote":"`/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.","summary":"35 plugins exposing ~200 tools produced a fixed per-request overhead larger than a 32k window, bricking the session until /clear. Negative: past a point the definitions are not a cost, they are a wall.","author":"shaal","publisher":"GitHub","date":"2026-07-19","claim_ids":["c18"]},{"id":"s30","type":"runtime_receipt","url":"https://miscsubjects.com/a/mcp-tool-search-cost","title":"First-party: 831 published tool definitions, 127,440 tokens","quote":"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","summary":"Taken 2026-07-26 by POSTing tools/list to the live server and counting with tiktoken o200k_base. The command is printed in full on the page, so any reader can run it against any HTTP MCP server.","date":"2026-07-26","claim_ids":["c1","c2","c3"],"author":"","publisher":""},{"id":"s31","type":"runtime_receipt","url":"https://miscsubjects.com/a/mcp-tool-search-cost","title":"First-party: one real definition, 264 tokens, and where the tokens sit","quote":"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.","summary":"The anatomy measurement, same fetch and tokenizer as s30. Shows the folklore is half right: descriptions dominate cheap tools, schemas dominate expensive ones.","date":"2026-07-26","claim_ids":["c1","c3"],"author":"","publisher":""},{"id":"s32","type":"runtime_receipt","url":"https://developers.cloudflare.com/ai-gateway/observability/logging/","title":"First-party: a gateway log row, nine tools, 14,071 input tokens","quote":"{\"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}}","summary":"Read back on 2026-07-26 from the AI Gateway logs REST endpoint. metadata.tools is the count the client actually sent, and input_cached_tokens is the attribution-header effect standing at 12,480.","date":"2026-07-26","claim_ids":["c12","c4","c6"],"author":"","publisher":""},{"id":"s33","type":"runtime_receipt","url":"https://github.com/massoumicyrus/claude-code-cloudflare-gateway","title":"First-party: 856 definitions become 9 on the wire","quote":"ENABLE_TOOL_SEARCH=false tools=856  |  ENABLE_TOOL_SEARCH=true tools=9 [‘Agent’,‘AskUserQuestion’,‘Bash’,‘Edit’,‘Read’,‘Skill’,‘ToolSearch’,‘Workflow’,‘Write’]","summary":"Captured 2026-07-25 on claude-cli 2.1.165, same machine and prompt run twice against the local logging server. Shows the client, not the API, doing the deferral behind a non-first-party base URL.","date":"2026-07-25","claim_ids":["c10","c4"],"author":"","publisher":""},{"id":"s34","type":"runtime_receipt","url":"https://miscsubjects.com/a/mcp-tool-search-cost","title":"First-party: three configurations priced from gateway log rows","quote":"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","summary":"Measured 2026-07-25 on @cf/moonshotai/kimi-k2.7-code through a Cloudflare AI Gateway, same prompt and catalogue each time. The dollar column is the gateway’s estimate; the token counts are billed values.","date":"2026-07-25","claim_ids":["c12","c14","c4","c5"],"author":"","publisher":""}]}