On this page
Every tool an agent can call has to be described to the model, and the description is not sent once. It travels with every request in the conversation: name, description and JSON Schema, for every tool on every connected server, whether or not the model uses any of them that turn. Connect a few MCP servers and a sizeable part of the context window is spent before the user has typed a word.
How sizeable is a number most teams have never looked at. This article measures it. Nine widely used MCP servers were installed at pinned versions, each was asked for its tool listing, and the 153 definitions that came back were counted token by token: per server, per tool, and per session. Then the same listings were put through three kinds of reduction and two kinds of deferred loading, to see what each saves and what it puts at risk.
The headline figures: the nine servers together cost 22,203 tokens per request, which is 11% of a 200,000-token window and 666,090 tokens over a thirty-request session. Deferring definitions behind a search tool cut that by 82% to 95%. It also failed to find the right tool for a quarter of plainly worded requests, which is the part the savings figures leave out.
The problem
A model API is stateless. Each request carries the system prompt, the tool definitions, the conversation so far and the new message. The tool definitions sit near the top and are identical from one request to the next, so their cost is a fixed charge on every turn, multiplied by the length of the session.
%%{init: {'theme':'base','themeVariables':{'primaryColor':'#FFF3E0','primaryTextColor':'#232F3E','primaryBorderColor':'#FF9900','lineColor':'#232F3E','clusterBkg':'#F8FAFC','clusterBorder':'#CBD5E1','edgeLabelBackground':'#FFFFFF','nodeTextColor':'#232F3E'}}}%%
flowchart TD
S1["MCP server A
tools/list"] --> C["Client collects
every definition"]
S2["MCP server B
tools/list"] --> C
S3["MCP server C
tools/list"] --> C
C --> R["Each model request"]
R --> P1["System prompt"]
R --> P2["Tool definitions:
name, description, schema
for every tool"]
R --> P3["Conversation so far,
including tool results"]
R --> P4["New message"]
P2 --> N["Sent again on
every request"]
style P2 fill:#FEF2F2,stroke:#D13212,stroke-width:2px,color:#991B1B
style N fill:#FEF2F2,stroke:#D13212,stroke-width:2px,color:#991B1B
style C fill:#EBF8FF,stroke:#0073BB,stroke-width:2px,color:#004C74Three things follow from that. The definitions take room that the conversation could have used. They are billed as input tokens on every request, at full or cached rates. And a long list of tools makes the model’s choice harder, which is a quality cost on top of the token cost. Only the first two are measured here.
Test setup
The servers are ones a developer is likely to have connected: the reference servers for files, Git, memory, time, fetching and step-by-step reasoning, the reference test server, Microsoft’s Playwright server, and GitHub’s own server, measured twice because it ships with a default set of toolsets and an option to enable all of them.
| Server | Package and version | Tools |
|---|---|---|
| filesystem | @modelcontextprotocol/server-filesystem 2026.1.14 | 14 |
| memory | @modelcontextprotocol/server-memory 2026.1.26 | 9 |
| sequential-thinking | @modelcontextprotocol/server-sequential-thinking 2025.12.18 | 1 |
| everything | @modelcontextprotocol/server-everything 2026.1.26 | 13 |
| playwright | @playwright/mcp 0.0.68 | 22 |
| git | mcp-server-git 2026.1.14 | 12 |
| time | mcp-server-time 2026.1.26 | 2 |
| fetch | mcp-server-fetch 2025.4.7 | 1 |
| github, default toolsets | github-mcp-server v0.31.0 | 41 |
| github, all toolsets | github-mcp-server v0.31.0 with --toolsets all | 79 |
Each server was started as a local process and asked only for its listing. No tool was called, so no server read a file, opened a browser or reached the network; the GitHub server was given a placeholder in place of a token. The listing is read with the MCP Python SDK:
async def read_listing(command: list[str], env: dict[str, str] | None = None, timeout: float = 60.0, errlog: str = os.devnull) -> dict[str, Any]:
"""Returns the server's name and version, its tools as plain dictionaries, and how long the listing took.
The server's standard error goes to errlog, so that a server that fails to start can say why.
"""
parameters = StdioServerParameters(command=command[0], args=command[1:], env={**os.environ, **(env or {})})
with open(errlog, "w") as quiet, anyio.fail_after(timeout):
async with stdio_client(parameters, errlog=quiet) as (read, write):
async with ClientSession(read, write) as session:
started = time.perf_counter()
init = await session.initialize()
tools, cursor = [], None
for _ in range(MAX_PAGES):
page = await session.list_tools(cursor)
tools += [tool.model_dump(mode="json", by_alias=True, exclude_none=True) for tool in page.tools]
cursor = page.nextCursor
if not cursor:
break
return {"server": init.serverInfo.name, "version": init.serverInfo.version, "protocol": init.protocolVersion,
"instructions": init.instructions or "", "tools": tools, "seconds": round(time.perf_counter() - started, 2)}A model never sees MCP’s own JSON. The client converts each tool into the function-calling format of the API it uses, and three fields carry over everywhere: the name, the description and the parameter schema. Those three are what is counted, serialised as compact JSON and tokenised with o200k_base, with cl100k_base as a second opinion.
def definition(tool: dict[str, Any]) -> dict[str, Any]:
"""The part of an MCP tool that reaches a model, in the shape function-calling APIs take."""
return {"name": tool["name"], "description": tool.get("description", ""), "parameters": tool.get("inputSchema", {"type": "object"})}
def tool_cost(tool: dict[str, Any], encoding: str = PRIMARY) -> dict[str, int]:
shaped = definition(tool)
return {"total": count(compact(shaped), encoding), "name": count(shaped["name"], encoding),
"description": count(shaped["description"], encoding), "schema": count(compact(shaped["parameters"]), encoding),
"characters": len(compact(shaped))}
def listing_cost(tools: list[dict[str, Any]], encoding: str = PRIMARY) -> int:
"""Tokens for a whole list of definitions, serialised together as one array."""
return count(compact([definition(tool) for tool in tools]), encoding) if tools else 0These are counts of the definitions, not figures from an invoice. Each provider wraps tool definitions in its own framing and uses its own tokeniser, so the billed number differs. The two tokenisers used here were within 3% of each other on the full set. Read the absolute figures as indicative, and the ratios between servers and between strategies as the result.
Tokens per server
| Server | Tools | Tokens | Median per tool | Largest tool | Share that is schema |
|---|---|---|---|---|---|
| filesystem | 14 | 1,699 | 112 | 190 | 53% |
| memory | 9 | 957 | 129 | 144 | 90% |
| sequential-thinking | 1 | 828 | 826 | 826 | 29% |
| everything | 13 | 1,116 | 79 | 208 | 78% |
| playwright | 22 | 2,500 | 104 | 263 | 92% |
| git | 12 | 1,107 | 68 | 260 | 93% |
| time | 2 | 238 | 118 | 158 | 94% |
| fetch | 1 | 237 | 235 | 235 | 73% |
| github, default toolsets | 41 | 6,986 | 147 | 404 | 84% |
| github, all toolsets | 79 | 13,537 | 132 | 573 | 87% |
| Nine distinct servers | 153 | 22,203 |

The spread is wide. The time and fetch servers cost about as much as a short paragraph. The GitHub server with every toolset enabled costs more than all the others combined, and its default configuration is already half of that. Tool count explains most of it: the median definition is between 68 and 147 tokens on every multi-tool server, so a server’s cost is close to its number of tools times a hundred or so.
Two rows break the pattern in opposite directions. The sequential-thinking server has one tool that costs 826 tokens, because its description is a 565-token essay on how to think. And the filesystem server is the only one where descriptions and schemas weigh about the same; everywhere else the schema is three quarters or more of the cost. When people talk about trimming tool descriptions, they are usually looking at the smaller part.
One comparison needs stating. Anthropic’s engineering article on advanced tool use, from November 2025, quotes about 26,000 tokens for a GitHub server with 35 tools. This run counted 6,986 tokens for 41 tools from version 0.31.0. I cannot reconcile the two from outside: the server version and configuration differ, the tokeniser differs, and their figure is measured as the model receives it, with whatever framing the platform adds. Treat the counts here as the content of the definitions and expect the billed figure to be higher.
Tokens per tool
Across the 153 definitions, 66 are under 100 tokens, and the ten largest hold a fifth of the total. There is no single offender to remove; the weight is spread across many medium-sized schemas.
| Largest definitions | Tokens | Description | Schema |
|---|---|---|---|
sequential-thinking.sequentialthinking | 826 | 565 | 234 |
github.actions_list | 573 | 35 | 526 |
github.projects_write | 567 | 19 | 539 |
github.pull_request_read | 404 | 12 | 382 |
github.projects_list | 356 | 31 | 313 |
The large GitHub tools share a design: one tool with a method parameter that selects among several operations, and a schema that describes the arguments of all of them. That keeps the tool count down and moves the cost into the schema. It is a reasonable trade for the model’s choice among tools, and it is why counting tools alone understates a server.
Server instructions are a separate charge that the tables above leave out. Most of these servers send none. The GitHub server sends 377 tokens of instructions with its default toolsets and 1,380 with all of them, and a client that passes them to the model pays for those on every request as well.
Tokens per session
A per-request figure becomes a session figure by multiplication. Thirty model requests is taken here as one working session for a coding agent; every tool call is followed by another request, so the count rises quickly.
| Setup | Servers | Tools | Tokens per request | Share of a 200,000-token window | Over 30 requests |
|---|---|---|---|---|---|
| Coding agent: filesystem, git, github, playwright | 4 | 89 | 12,286 | 6.1% | 368,580 |
| The same with all GitHub toolsets | 4 | 127 | 18,837 | 9.4% | 565,110 |
| Research assistant: fetch, memory, time, sequential-thinking | 4 | 13 | 2,254 | 1.1% | 67,620 |
| Everything connected | 9 | 153 | 22,203 | 11.1% | 666,090 |
On a 128,000-token window the last row is 17.3%. That is before the system prompt, before any file has been read, and before the tool results, which are usually larger than the definitions that produced them.
Reducing definitions
The first response is to make each definition smaller. Three levels were tried, from safe to aggressive.
def strip_generated(tool: dict[str, Any]) -> dict[str, Any]:
"""Level 1: remove schema titles and $schema. Nothing a model relies on is lost."""
slim = copy.deepcopy(tool)
slim["inputSchema"] = walk(slim.get("inputSchema", {}), without(*GENERATED))
return slim
def short_description(tool: dict[str, Any]) -> dict[str, Any]:
"""Level 2: level 1, and keep only the first sentence of the tool description."""
slim = strip_generated(tool)
slim["description"] = first_sentence(slim.get("description", ""))
return slim
def bare_schema(tool: dict[str, Any]) -> dict[str, Any]:
"""Level 3: level 2, and drop parameter descriptions and defaults. Names and types are all that is left."""
slim = short_description(tool)
slim["inputSchema"] = walk(slim["inputSchema"], without("description", "default"))
return slim| Reduction | Tokens for 153 tools | Saved |
|---|---|---|
| As published | 22,203 | |
1. Strip generated fields (title, $schema) | 21,051 | 5.2% |
| 2. Also keep only the first sentence of each description | 18,928 | 14.8% |
| 3. Also drop parameter descriptions and defaults | 11,227 | 49.4% |
Level 1 is free: schema titles and the $schema marker are produced by tooling and carry nothing a model needs. It saved 12% to 18% on the servers built with the TypeScript and Python SDKs and nothing at all on the GitHub server, whose schemas are already written without them. Level 2 matters only where descriptions are long, which means the filesystem server (46%) and sequential-thinking (71%). Level 3 halves the total, by removing the text that tells a model what each parameter means.
No model was called in this run. Levels 2 and 3 remove text a model reads when it chooses a tool and fills in arguments, and the effect on its choices is not measured here. Apply level 1 freely. Test anything beyond it with the agent and the tasks that will use it.
Deferred loading with tool search
The second response is to stop sending most definitions at all. The model is given one small tool that searches an index of the others, and full definitions are added to the conversation only when a search returns them. Anthropic shipped this as a platform feature in November 2025, with regular-expression and BM25 search built in, and the pattern can be built on any API.
%%{init: {'theme':'base','themeVariables':{'primaryColor':'#FFF3E0','primaryTextColor':'#232F3E','primaryBorderColor':'#FF9900','lineColor':'#232F3E','signalColor':'#0073BB','signalTextColor':'#0F172A','actorBkg':'#FFF3E0','actorBorder':'#FF9900','actorTextColor':'#232F3E','noteBkgColor':'#FFF8E7','noteBorderColor':'#FF9900','noteTextColor':'#232F3E'}}}%%
sequenceDiagram
participant M as Model
participant C as Client
participant I as Tool index
participant S as MCP server
C->>M: Request with one tool: search_tools
M->>C: search_tools("open an issue")
C->>I: Rank 153 definitions
I-->>C: Top 5 definitions
C->>M: Definitions added to the conversation
M->>C: Call issue_write
C->>S: tools/call issue_write
S-->>C: Result
C->>M: Result, definitions stay loadedThe index in the sample is BM25 over the words in each tool’s name, description and parameter names:
class ToolIndex:
def __init__(self, tools: list[dict[str, Any]], k1: float = 1.5, b: float = 0.75) -> None:
self.tools, self.k1, self.b = tools, k1, b
self.documents = [Counter(document(tool)) for tool in tools]
self.lengths = [sum(doc.values()) for doc in self.documents]
self.average = sum(self.lengths) / max(len(self.lengths), 1)
spread = Counter(term for doc in self.documents for term in doc)
self.idf = {term: math.log(1 + (len(tools) - n + 0.5) / (n + 0.5)) for term, n in spread.items()}
def search(self, query: str, limit: int = 5) -> list[dict[str, Any]]:
terms, scored = words(query), []
for index, doc in enumerate(self.documents):
score = 0.0
for term in terms:
frequency = doc.get(term, 0)
if frequency:
norm = frequency + self.k1 * (1 - self.b + self.b * self.lengths[index] / self.average)
score += self.idf[term] * frequency * (self.k1 + 1) / norm
if score > 0:
scored.append((score, index))
scored.sort(key=lambda pair: (-pair[0], pair[1]))
return [self.tools[index] for _, index in scored[:limit]]The saving depends on the search finding the right tool, so that was measured first. Sixty-nine requests were written by hand, each with the one tool that should answer it, phrased the way a person would ask and not adjusted after the search was run.
| Expected tool was | Requests | Share |
|---|---|---|
| Ranked first | 24 of 69 | 35% |
| In the top 5 | 44 of 69 | 64% |
| In the top 10 | 51 of 69 | 74% |
| Not found at all | 18 of 69 | 26% |
The misses are instructive because they are so ordinary. “What files are in the src folder” does not find list_directory. “Remember that Alice is a person who works at Acme” does not find create_entities. “Which files have I changed locally but not committed” does not find git_status. People describe what they want, tools are named for what they do, and a keyword index only matches when the two happen to share words.
With that hit rate, a thousand simulated sessions of thirty requests give this:
| Distinct tools used in the session | All definitions up front | Deferred, mean | Saved | Definitions loaded by the end | Sessions where a tool was never found |
|---|---|---|---|---|---|
| 2 | 666,090 | 34,895 | 94.8% | 12 | 47.9% |
| 4 | 666,090 | 63,579 | 90.5% | 23 | 69.5% |
| 8 | 666,090 | 117,803 | 82.3% | 42 | 93.9% |

The savings are real and large: 82% to 95% fewer tokens spent on definitions. So is the last column. In nearly half of the two-tool sessions, at least one tool was not in the top ten results for its request, and a model that cannot find a tool cannot call it. The failure column is a property of this index and these phrasings, not of deferred loading as such. A model writes its own search queries and tends to use tool-like vocabulary, and an embedding index matches meaning where BM25 matches words. Both should do better. Neither was measured here, and the lesson holds either way: the saving is only worth having at the hit rate you have measured on your own tools.
Deferred loading with a catalogue
There is a variant that removes the retriever. Keep a short catalogue of every tool in the prompt, one line each, and give the model a tool that loads full definitions by exact name. The model does the matching, which it is better at than a keyword index, and the cost is the catalogue itself.
def catalogue(tools: list[dict[str, Any]], with_summary: bool) -> str:
"""A compact list of every tool for the prompt: its name, and optionally the first sentence of its description."""
lines = []
for tool in tools:
summary = tool.get("description", "").strip().replace("\n", " ").split(". ")[0].rstrip(".") if with_summary else ""
lines.append(f"{tool['server']}.{tool['name']}" + (f": {summary}" if summary else ""))
return "\n".join(lines)| Catalogue kept in the prompt | Tokens | Saved with 2 tools used | With 4 | With 8 |
|---|---|---|---|---|
| Names only | 1,034 | 94.4% | 93.7% | 92.2% |
| Names and the first sentence of each description | 2,655 | 87.1% | 86.4% | 84.9% |
A names-only catalogue of 153 tools costs 1,034 tokens, under 5% of the full definitions, and only the tools that are used get loaded, so the saving holds as sessions grow. Whether a model picks the right name from a bare list is again something this run cannot say. Names such as issue_write and browser_take_screenshot are self-explanatory. Names such as create_entities are not, which is the case for paying for the first sentence as well.
Cost
Converted to money, the definitions are a small line per session and a visible one at volume. As an illustration only, at a price of 2 US dollars per million input tokens, the nine-server setup spends 1.33 dollars per thirty-request session on tool definitions before any caching, and a thousand sessions a day is about 40,000 dollars a month. Substitute your own model’s price; the token counts are what the run establishes.
Prompt caching changes the arithmetic more than any trimming does. Tool definitions sit at the start of the request and do not change, so they are the part of a prompt most likely to be served from cache at a fraction of the normal rate. That also sets a constraint on deferred loading. A design that edits the tool list in the middle of a session changes the start of the prompt and can lose the cache for everything after it. Anthropic’s article says its feature keeps the cache intact because deferred tools are left out of the initial prompt and added only after a search. A home-built version should append in the same way and never rewrite the list.
Production considerations
- Measure before choosing. Reading all ten listings took under four seconds in this run. Put the count in CI with a budget, so that a server upgrade that adds twenty tools is seen in a pull request and not on an invoice.
- Server configuration first. The cheapest reduction is not enabling what is not needed. The GitHub server went from 13,537 tokens to 6,986 by staying on its default toolsets, and it also has a read-only mode that leaves out every tool that writes.
- Keep the common tools loaded. Deferred loading adds a search step and a model round trip before a tool can be used. Anthropic’s guidance is to keep the three to five most used tools in the prompt and defer the rest.
- Stable ordering. Send definitions in the same order every time. A list that is reshuffled between requests cannot be cached.
- Tool results. A page snapshot from a browser tool or a file from a filesystem tool is often larger than every definition combined, and it stays in the conversation. Budget for results separately.
- Limits. A client should cap the size of a listing it accepts. The red-team tests showed a plain client accepting a 5,000-tool listing and a one-megabyte description without complaint.
- Review of trimmed text. If descriptions are shortened by a proxy, the model no longer sees what the server author wrote. Keep the transformation in version control and treat a change to it like a change to a prompt.
%%{init: {'theme':'base','themeVariables':{'primaryColor':'#FFF3E0','primaryTextColor':'#232F3E','primaryBorderColor':'#FF9900','lineColor':'#232F3E','clusterBkg':'#F8FAFC','clusterBorder':'#CBD5E1','edgeLabelBackground':'#FFFFFF','nodeTextColor':'#232F3E'}}}%%
flowchart TD
A["Count tokens of all
tool definitions"] --> B{"Under 5% of
the context window?"}
B -- "yes" --> C["Strip generated fields,
rely on prompt caching"]
B -- "no" --> D["Disable toolsets and
tools you do not use"]
D --> E{"Still over budget?"}
E -- "no" --> C
E -- "yes" --> F["Keep the most used
tools loaded"]
F --> G2{"Measured search hit rate
on your own requests"}
G2 -- "high" --> H["Defer the rest
behind tool search"]
G2 -- "low or unknown" --> I["Defer the rest behind a
catalogue and load by name"]
style C fill:#F0FFF4,stroke:#1D8102,stroke-width:2px,color:#145202
style H fill:#EBF8FF,stroke:#0073BB,stroke-width:2px,color:#004C74
style I fill:#EBF8FF,stroke:#0073BB,stroke-width:2px,color:#004C74
style D fill:#F3E8FF,stroke:#7C3AED,stroke-width:2px,color:#4C1D95Decision framework
| Your situation | What to do | Why |
|---|---|---|
| One or two small servers, a dozen tools | Nothing beyond stripping generated fields | About 2,000 tokens per request is 1% of the window, and caching covers it |
| A coding agent with a large server such as GitHub | Choose toolsets deliberately, then measure again | Default against all toolsets was a factor of two in this run |
| Many servers, most tools unused in any one session | Deferred loading, with the common tools kept loaded | 82% to 95% of definition tokens saved |
| Deferred loading with keyword search | Measure the hit rate on real requests first | A quarter of plainly worded requests found nothing here |
| Tool names that explain themselves | A names-only catalogue with load-by-name | 1,034 tokens for 153 tools, and no retriever to tune |
| Pressure to shorten descriptions | Test with the agent before and after | The saving is small on most servers and the effect on tool choice is unmeasured |
Key takeaways
- Tool definitions are sent on every request. Nine common MCP servers cost 22,203 tokens per request in this run, 11% of a 200,000-token window, and 666,090 tokens over thirty requests.
- Cost follows tool count: about a hundred tokens per tool on most servers, with the schema, not the description, making up three quarters or more.
- Configuration beats trimming. Stripping generated schema fields saved 5%. Leaving the GitHub server on its default toolsets saved 48% of that server’s cost.
- Deferred loading saved 82% to 95%, and keyword search failed to find the right tool for 26% of plainly worded requests. Measure the hit rate before trusting the saving.
- A names-only catalogue with load-by-name cost 1,034 tokens for 153 tools and needs no retriever. It is the simplest form of deferral to build and to reason about.
If you have measured the tool overhead of your own agent setup, leave a comment with the server list and the count. Figures from real configurations are more useful than any single run.
Everything above ran in GitHub Actions on a hosted Linux runner with Python 3.13.18, Node.js 22, MCP Python SDK 1.26.0 and tiktoken 0.12.0, with the server versions in the table and other dependencies resolved as they stood on 4 March 2026. Each server was started as a local process and asked for its tool listing; no tool was called. The run counted tokens for all 194 listed definitions (153 distinct, since the default GitHub toolsets are part of the full set), applied three reductions, ran a BM25 index against 69 hand-written requests, and simulated 1,000 sessions for each of six deferral settings with a fixed random seed. 13 unit tests cover the reductions, the index and the counter. Not run: any model, so billed tokens, tool selection after trimming, search with model-written queries and prompt caching are not measured; an embedding index; tool results. The requests were written by hand for this lab and are not a benchmark. Token prices in the cost section are an illustration, not a quotation. The run is here.
The complete sample for this article is on GitHub: nithinmohantk/blog-samples-working-repo/mcp-context-cost. Clone it with git clone https://github.com/nithinmohantk/blog-samples-working-repo.git and open the mcp-context-cost folder. Its README says how to run it and what has been verified.
Glossary
- Tool definitionβ The name, description and parameter schema of a tool, as sent to a model.
- Context windowβ The maximum number of tokens a model can take in one request, including everything listed here.
- Tokenβ The unit a model reads and is billed in; roughly three to four characters of English or JSON.
- Tokeniserβ The scheme that splits text into tokens. Counts differ between tokenisers, here by under 3%.
- Deferred loadingβ Keeping tool definitions out of the prompt until the model asks for them.
- Tool searchβ A tool that searches an index of other tools and returns their definitions.
- BM25β A keyword ranking function that scores documents by the query words they contain.
- Catalogueβ A short list of every tool, kept in the prompt so that the model can ask for one by name.
- Toolsetβ A named group of tools that a server can enable or disable as a unit.
- Prompt cachingβ Billing a repeated start of a prompt at a reduced rate when it matches an earlier request.
References & Further Reading
- → MCP specification 2025-11-25: Toolsβ What a tool definition contains and how listings are paginated
- → Anthropic: Advanced tool useβ The tool search tool, deferred loading, and the vendor’s own token figures
- → GitHub MCP serverβ Toolsets, the default set and how to enable all of them
- → mcp on PyPIβ The Python SDK used to read each listing
- → tiktoken on PyPIβ The tokeniser library used for the counts
- → Red-Teaming an MCP Serverβ Why a client should cap the size of a listing it accepts
- → Sample code for this articleβ Collector, token counter, reductions, tool index, task set and the CI script
Discover more from C4: Container, Code, Cloud & Context
Subscribe to get the latest posts sent to your email.