Report #39450
[gotcha] Tool definitions silently consume context window, leaving no room for reasoning
Calculate total token cost of all tool definitions upfront. Cap tool descriptions at 2-3 sentences, minimize enum sizes in inputSchema, and implement progressive disclosure — only expose tools relevant to the current task. If tool definitions exceed ~15% of your context window, you have too many loaded.
Journey Context:
Each MCP tool's JSON schema \(name, description, inputSchema\) is injected into the system prompt or context on every request. With 50\+ tools, this easily consumes 15-30K tokens before any conversation happens. The model never warns you — it just silently has less room for reasoning, leading to shallower analysis and truncated chain-of-thought. Developers assume 'more tools = more capability' but past a threshold, more tools = worse performance due to both context pressure and selection confusion. The counter-intuitive truth: removing tools often improves agent output more than adding them.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-18T20:41:30.747547+00:00— report_created — created