Verbose MCP tool descriptions dominate context cost over parameter count

u/LorenzoNardi continued their MCP token tracking series with a controlled experiment using the same MCP server and a fixed task set covering file operations, search, and write tasks. Across 200 logged calls, they varied tool descriptions from minimal (one sentence) to verbose (full examples plus edge cases), and varied parameter counts from 2 to 8 per tool, then measured total context tokens consumed per session.

The most notable finding was that 2–3 extra optional parameters with defaults had almost no measurable impact in practice, because the model skipped them in roughly 85% of calls.

The numbers showed a clear asymmetry: verbose descriptions added approximately 340 tokens per tool to the system prompt compared to minimal descriptions, while each additional parameter contributed only about 80 tokens on average. At 10 tools, verbose descriptions outweighed the cost of extra parameters by roughly 2x; at 20 or more tools, description length became the dominant cost driver by approximately 4x.

The most notable finding was that 2–3 extra optional parameters with defaults had almost no measurable impact in practice, because the model skipped them in roughly 85% of calls. Long descriptions, by contrast, are loaded into context on every single call regardless of relevance. The post concludes that for large MCP servers, trimming descriptions is the higher-leverage optimization — and that one-line descriptions paired with well-named parameters outperformed verbose documentation on both token cost and call accuracy in these tests.

Key facts

1. 01200 MCP tool calls were logged using the same server and task set (file ops, search, write)
2. 02Verbose descriptions added ~340 tokens/tool to the system prompt vs. minimal (one-sentence) descriptions
3. 03Each additional parameter added ~80 tokens on average
4. 04At 10 tools, verbose descriptions outweigh extra parameters by ~2x in token cost
5. 05At 20+ tools, description length becomes the dominant cost driver by ~4x
6. 06Optional parameters with defaults were skipped by the model in ~85% of calls, contributing near-zero token overhead in practice
7. 07One-line descriptions with good parameter names outperformed verbose docs on both token cost and call accuracy

Topics