The Token Cost of MCP Server Tool Lists: A 34,374-Listing Empirical Study

Every AI model request re-sends the full tool list of MCP servers—just how large is this "invisible overhead"? An empirical study covering 34,374 servers provides the answer: the median is about 1,300 tokens, but the heaviest listing reaches 540,000 tokens—enough to blow out the context window.

Why tool lists become a cost item

MCP (Model Context Protocol) lets AI clients connect to external tool servers, and a server's tools/list defines which operations it can offer. The problem is that the client stuffs this entire list into the prompt on every model request.

An earlier survey of 12,915 MCP servers found 182,157 tool definitions spread across 7,656 servers, averaging about 24 tools per server. Readers followed up: if this list is re-sent on every request, what exactly is its token cost?

HISTOR (public MCP server logs) decided not to sample but to count everything: as of October 19, 2026, covering 18,204 npm and PyPI packages and 16,170 remote servers.

MCP's tools/list returns a structured array of tool definitions, each typically containing name (the tool name), description (a natural-language description), and input_schema (a parameter specification in JSON Schema format). The client serializes this entire array and embeds it in the system prompt or a dedicated field, so token consumption is essentially the length of this JSON text. JSON Schema allows nested objects, enums, default values, and description fields, so a tool with complex parameters can have a schema that alone contains hundreds of tokens.

This is also why the phenomenon of "few tools but many tokens" holds: a tool with a dozen parameters, each carrying a description and enum constraints, can have a schema far larger than ten tools with only a single string parameter each. Understanding this is necessary to judge whether cost reduction should start with trimming descriptions or restructuring schemas.

Methodology

The counting method simulates how a client builds a request: for each tool it takes name, description, and input_schema, serializes them to compact JSON, then counts tokens. The tokenizer is o200k_base (tiktoken 0.12). Each server with at least one tool counts once, using the last listing observed by HISTOR.

Core data: cheap median, shocking long tail

Metric	Packages	Remote servers
Servers	18,204	16,170
Total tool definitions	337,449	232,427
Tools per server (median/mean)	8 / 18.5	7 / 14.4
Median tokens per server	1,272	1,328
Mean	3,812	3,412
90th percentile	8,361	7,425
99th percentile	39,612	22,294
Maximum	304,780	547,935

Three findings are worth noting.

The mean is three times the median. The typical server is cheap, but a few servers with hundreds or thousands of tools contribute most of the tokens. The "about 24 tools" from the earlier survey was a mean; expanded to a larger dataset, the mean drops to 18.5 and the median is just 8.

The heaviest lists don't necessarily have the most tools. The largest remote listing contains 71 tools yet occupies 547,935 tokens, about 7,700 tokens per tool; another remote server occupies 175,588 tokens with just 15 tools. What makes a list heavy is the bulk of individual definitions, not the number of tools—when each tool costs thousands of tokens, a single description or input schema becomes a document in itself.

Some lists simply don't fit. 304,780 tokens already exceeds a 200,000-token context window; once a client connects to that package, there's no room left even for the question.

Converting to real money

Tool lists are sent with every request, so cost equals tokens × unit price × number of requests. At prices as of October 19, 2026, the cost per 1,000 requests is as follows:

Single server's list	Tokens	$0.10/M (small model)	$2/M (mid-size model)	Mid-size model with prompt caching
Median package	1,272	$0.13	$2.54	$0.13
Mean package	3,812	$0.38	$7.62	$0.38
90th percentile	8,361	$0.84	$16.72	$0.84
99th percentile	39,612	$3.96	$79.22	$3.96

A client connected to five median servers has already sent about 6,400 tokens of tool definitions before the user types the first character.

Prompt caching is a billing optimization offered by major model APIs: when the prefix portion of a request (usually the system prompt and tool definitions) is exactly identical to the previous request, the provider can reuse the already-computed KV cache and bill at a price far below the input rate. The "one-twentieth" mentioned in the article is a typical order of magnitude for cache-read discounts; the exact ratio varies by provider.

The key condition for a cache hit is that the prefix is byte-for-byte stable. If the client re-serializes the tool list on every request, reorders tools, or inserts dynamic content (such as timestamps or user state) before the list, the cache misses and you pay full price. So prompt caching is not an automatic money-saver but an engineering constraint the client must deliberately maintain at the request-construction level.

How to cut this overhead

Prompt caching. If the client keeps the tool list unchanged and places it early in the prompt, cache-read pricing is about one-twentieth of the input price. But once the client reorders tools or rebuilds the list on every request, that discount is gone.

Load definitions on demand. The model first sees only tool names and fetches the schema only when it's actually about to call one.

Publishers should slim down definitions. Descriptions should state only what the tool does and when to use it, nothing else; schemas should avoid repeated prose-style explanations; reduce the number of tools, or merge related operations behind a single tool with an action parameter. The median tokens per tool is 129 for packages and 231 for remote servers—a listing at 7,700 tokens per tool clearly has something else going on.

"Loading definitions on demand" usually corresponds to two engineering patterns. The first is two-phase invocation: the first request exposes only tool names and a one-line purpose, and once the model picks a tool, a second request fetches the full schema and executes it—at the cost of an extra round trip. The second is tool retrieval: treating the tool list as a searchable corpus, running vector or keyword retrieval against the user's query first, and injecting only the most relevant tool definitions into the prompt.

Both patterns sacrifice some of the convenience of "the model sees all capabilities at once" in exchange for savings in context and cost. For servers with few tools (such as the median of 8), sending everything is still worthwhile; the benefit of on-demand loading shows up mainly in long-tail servers with many tools and heavy individual definitions.

Measure it yourself

The project offers a free counter at modelmarket.dev/tools/tool-list-cost: paste a tools/list, or specify a server observed by HISTOR (an https endpoint, npm:<package>, pypi:<package>, or a registry name), and get the token count, its rank among the 34,374 servers, the cost per thousand requests, the heaviest tool, and a one-line badge snippet for your README.

The page uses the same tokenizer as the data above and was compared against tiktoken on 120 HISTOR tool listings (2.6 million tokens total), with zero discrepancies. Pasted lists are counted in memory only and are not saved; queries only access HISTOR and never contact the target server.

What these numbers don't measure

• Only one tokenizer. Other models count differently, usually by tens of percentage points, but the overall shape is consistent: a median near 1,300 tokens plus a long tail.
• Provider-side text is not included. Model APIs wrap tool definitions in their own instructions, which are not counted here.
• What clients actually send may differ. Some drop fields or truncate descriptions; some also send output schemas. Counting the full list, the median for packages is 1,390 tokens and the 90th percentile is 9,960.
• Server popularity is not weighted. Each listed server counts once, so a popular server and an abandoned one carry equal weight.

Tokenizer differences deserve elaboration: o200k_base is the BPE tokenizer used by OpenAI-series models, while Claude, Gemini, and others use their own tokenization schemes. JSON and code-like text typically show larger tokenization granularity differences across tokenizers than natural language does, because punctuation, underscores, and camelCase are merged or split differently. A deviation of tens of percentage points means the absolute values in this article can't be applied directly to other models, but three structural conclusions remain robust across tokenizers: a median of about 1,300 tokens, a mean several times the median, and an extreme long tail.

Reproducibility

The methodology and implementations in five languages are in the docs/tool-list-cost.md file of the alexar76/histor repository; the counting script is scripts/tool_list_tokens.py (the export query is written in its docstring), and summary data without server names is in docs/tool-list-tokens-2026-10-19.json.

For developers in the MCP ecosystem, this data sends a clear signal: a tool list is not free metadata but a toll you pay again on every conversation. Keeping descriptions and schemas restrained when designing tools, and making good use of caching and on-demand loading on the client side, are the two most direct cost-saving levers available today.

One-line Summary

Measured across 34,374 MCP servers: tool-list tokens have a median around 1,300, with the heaviest reaching 548K—enough to blow out the context.

Paragraph Summary

HISTOR ran a full token census of tool lists across 34,374 MCP servers (18,204 npm/PyPI packages and 16,170 remote servers). Results show a median of about 1,272–1,328 tokens, but a mean as high as 3,400–3,800, with a heavy-tailed distribution: the 90th percentile is around 8,000, the 99th percentile is 20,000–40,000, and the largest remote listing is 548,000 tokens—already beyond a 200,000-token context window. List weight depends on the bulk of individual tool definitions (descriptions and schemas) rather than the number of tools—the largest remote listing has only 71 tools yet occupies 548,000 tokens, about 7,700 per tool. In cost terms, five median servers have already sent about 6,400 tokens before the user asks anything. The author recommends prompt caching, on-demand definition loading, leaner descriptions and schemas, and merging operations to cut overhead, and provides a free measurement tool.