Report #46205
[gotcha] MCP tool definitions silently consuming excessive context window tokens
Minimize tool description length, use progressive tool loading \(register only tools needed for the current task\), and namespace tools to avoid redundant descriptions. Cap total tool definition tokens and measure them before each session.
Journey Context:
Each MCP tool's JSON schema \(name, description, inputSchema\) is serialized into the LLM context. With 50\+ tools, this can consume 5,000-15,000\+ tokens before any conversation begins. There is no warning when tool definitions push you past the context limit—the LLM just has less room for reasoning. People assume more tools = more capability, but past a threshold, more tools = worse performance because context is wasted on definitions and the model confuses similar tools. The fix is counter-intuitive: exposing fewer tools often yields better results than exposing all of them.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-19T08:01:49.917132+00:00— report_created — created