[BUG] Built-in tools + MCP descriptions load on first message causing 10-20k token overhead
Status Fixed / completed
Maintainer reply ✓ Yes — rboyce-ant
Workaround ✓ Mentioned in description ↑
Activity 7 comments · opened Jul 12, 2025 · closed Jul 13, 2025
💡 Likely answer: A maintainer (rboyce-ant, contributor)
responded on this thread — see the highlighted reply below.
[BUG] All tool descriptions load on first message causing 10-20k token overhead
Environment
- Platform (select one):
- [x] Anthropic API
- [ ] AWS Bedrock
- [ ] Google Vertex AI
- [ ] Other: <!-- specify -->
- Claude CLI version: 1.0.51
- Operating System: macOS 14.5
- Terminal: Warp
Bug Description
Claude Code loads ALL tool descriptions (both built-in and MCP) into context immediately after the first user message, regardless of whether any tools are needed. This causes massive token consumption even for simple queries.
Token Analysis (observed with --verbose):
- Built-in tools: Approximately 10,000-11,000 tokens (this seems to affect all users)
- With MCP servers: Additional 4,000-8,000+ tokens
- Total overhead: 10,000-20,000+ tokens on every conversation start
This means even asking "hello" or "what's 2+2?" triggers loading of:
- 15 built-in tools (Task, Bash, Grep, Read, Edit, MultiEdit, Write, WebFetch, WebSearch, TodoWrite, NotebookRead, NotebookEdit, LS, Glob, exit_plan_mode)
- Plus any configured MCP tools
- All with verbose descriptions
Steps to Reproduce
- Launch Claude Code with verbose flag:
claude --verbose - Type any simple message: "hello", "what's 2+2?", or "how are you?"
- Observe token count jumping from ~0 to:
- Without MCP: ~11,600 tokens
- With 4 MCP servers: ~15,000 tokens
- With 7+ MCP servers: ~20,000+ tokens
Expected Behavior
- Tool descriptions would ideally load only when needed for the specific task
- Simple queries like "hello" or "what's 2+2?" would use minimal tokens
- Token consumption would scale with actual tool usage
Actual Behavior
- ALL tool descriptions load immediately after first message
- Every conversation starts with 10,000+ token overhead
- Simple "hello" costs same tokens as complex tool-using tasks
- Built-in tools alone consume ~10,600 tokens (before any MCP)
Additional Context
Real Example:
User: "What's 2+2?"
Token consumption:
- Before message: ~1,000 tokens
- After message: ~15,000 tokens (with 4 MCPs)
- Actual response: "4" (~5 tokens)
- Wasted tokens: ~14,000
- Cost overhead: ~$0.21 per simple questionImpact:
- Based on my testing, every conversation appears to start with ~10,000+ tokens for built-in tools
- Users with MCP integrations see even higher consumption (15,000-20,000+ tokens)
- This makes simple queries unexpectedly expensive
- The token overhead is the same whether asking "hello" or performing complex tasks
- In my case with multiple MCP servers configured, I had to disable several to reduce token consumption by 30,000-35,000 tokens per conversation start
Current Workarounds I'm Using:
- Disabled several MCP servers to reduce token consumption
- Batching multiple questions in one session when possible
- Using
/compactcommand more frequently
Note:
This behavior appears to be new in v1.0.51. I don't recall seeing this level of token consumption in previous versions.
Related Issues:
- This seems distinct from #2638 (MCP response truncation)
- Different from #2320 (token limits with
/mcp list) - The main observation: all tool descriptions appear to load after the first message
7 Comments
I don't believe this is anything new – we always provide local & MCP tools directly to the model. You can disable tools that you don't want to use with the
--disallowedToolsCLI flag, or in settings.json. If you deny an entire tool, the tool prompt won't be included in context.If you want to ask simple questions to Claude models without any tools, you might also want to use the Anthropic API directly instead of using Claude Code.
@rboyce-ant Thank you for taking the time to clarify this! The --disallowedTools flag is really helpful to know about.
One thing I noticed while researching MCP optimization is that the official docs don't explicitly state when tokens are consumed - whether it's at server connection time (when tool descriptions are loaded) or only during tool invocation.
This leaves developers guessing about the token impact of having multiple MCP servers connected but idle. Would be helpful if the docs clarified whether:
Tool manifests consume tokens immediately when servers connect
Or tokens are only used when tools are actually called
Just a documentation suggestion that could help developers make more informed architectural decisions. Really appreciate your work on Claude Code and the MCP ecosystem!
@pavveu the model has to know what tools are available before it can invoke them. This has to be done ahead of time. So you have to tell the model all the tools/descriptions before it can reason about whether to use one - maybe this belongs in the User Guide, but IMO it's just part of "how LLMs work" and if it "leaves developers guessing" that's due to unclarity about tools and not about MCP per se, but maybe there is a place to add the information, I don't consider it really part of "MCP".
@hesreallyhim Regardless of whether this is "basic LLM knowledge" or not, if developers are discovering costly token consumption through trial and error, that's a documentation gap worth fixing. Good documentation meets users where they are, not where experts think they should be.
@pavveu that's fair, I'm not going to litigate whether this counts as "expert knowledge" but sure. I mean I consider Bash man pages pretty confusing, and they assume you know a lot about Bash, but they're probably considered good documentation nonetheless. So, hard to say where to draw the line, but fair enough. should they also explain how system prompts work in general? (probably this is documented actually in the material about prompt caching...) anyway I hope it's clear now and now you're an expert too. 😄
"Each one teach one" then we wouldn't need documentation 🤣 sorry just having some fun but it's also a good message
@hesreallyhim haha yeah "each one teach one" 😄
Funny thing - I used the research features in both claude.ai and perplexity to look this up, and got pretty confusing results. Should've probably just read the docs 2-3 times (though aren't these tools supposed to save us time?).
Definitely gonna check the sources myself next time instead of just trusting the summaries (even if some of them check 400 links).
Still think a heads up in the docs would be nice though - something like:
Note: Token Usage - All MCP tool schemas are included in every request to the LLM, which impacts token consumption. For example, 10 tools with detailed descriptions might add around 1000-5000 tokens to each request.
But its not my decision to make ;)
This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.