Issue Station
Sign In
Tools hereToolbox

claude-code - 💡(How to fix) Fix MCP tool-catalog mode — surface tool name+description without full schemas [1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
anthropics/claude-code#55642•Fetched 2026-05-03 04:48:09
View on GitHub
Comments
0
Participants
1
Timeline
3
Reactions
0
Author
brandonrdugbrandonrdug
Participants
brandonrdugbrandonrdug
Timeline (top)
labeled ×3

Root Cause

For our use case (~80 projectmeta MCP tools, total 42-70K tokens for full schemas, ~1-2K tokens for name+description list), neither end of the threshold fits:

  • Default (true/unset) — defers all → the assistant keyword-searches blindly via the ToolSearch tool because it has no descriptions to differentiate similarly-named tools
  • ENABLE_TOOL_SEARCH=false — loads 4-7% of a 1M context window upfront for what may be a small task

Fix Action

Fix / Workaround

Workaround in use

RAW_BUFFERClick to expand / collapse

The gap

ENABLE_TOOL_SEARCH=auto:N is a global threshold (load all OR defer all based on % of context). It doesn't expose the case where the assistant should know what tools exist (compact name + description per tool, ~50-80 chars each) without paying for full JSONSchemas (200-1500 bytes each).

For our use case (~80 projectmeta MCP tools, total 42-70K tokens for full schemas, ~1-2K tokens for name+description list), neither end of the threshold fits:

  • Default (true/unset) — defers all → the assistant keyword-searches blindly via the ToolSearch tool because it has no descriptions to differentiate similarly-named tools
  • ENABLE_TOOL_SEARCH=false — loads 4-7% of a 1M context window upfront for what may be a small task

We measured this empirically: 211 ToolSearch loads in one ~32MB session JSONL, 43 (20%) of those loads were for tools that were never subsequently called — speculative searches because the assistant didn't know what each tool did.

Proposed

A third ENABLE_TOOL_SEARCH value or complementary setting (`MCP_TOOL_CATALOG=true` or tools/list?compact=true) where the assistant sees [{name, description}] per tool at session start, with full schemas still deferred behind the existing ToolSearch tool. The MCP spec's tools/list would need a compact-response option, OR Claude Code could project a compact view from the inline list it already has.

Cost-benefit: ~80 tools × ~80 chars description ≈ ~6.5KB ≈ ~1.6K tokens (~0.16% of 1M context). Eliminates the 20% speculative-load waste and lets the assistant pick the right tool on the first try.

Workaround in use

We're shipping a SessionStart additionalContext injection of the catalog (project-side hook) in our own MCP server's plugin. Works but must be reimplemented per project; a native CC mode would generalize.

Related

Happy to share session transcript samples privately if helpful for context.

extent analysis

TL;DR

Implement a new ENABLE_TOOL_SEARCH value or complementary setting to allow the assistant to load a compact tool catalog with names and descriptions at session start.

Guidance

  • Introduce a new setting, such as MCP_TOOL_CATALOG=true, to enable loading a compact tool catalog with names and descriptions.
  • Modify the tools/list endpoint to support a compact response option, returning a list of tool names and descriptions.
  • Update the assistant to use the compact tool catalog to inform its search queries, reducing speculative searches.
  • Consider implementing a native solution in Claude Code to project a compact view from the existing inline list of tools.

Example

No code snippet is provided as the issue does not contain sufficient technical details to generate a specific example.

Notes

The proposed solution aims to balance the trade-off between loading all tool schemas upfront and deferring all tool searches. The compact tool catalog is estimated to be approximately 6.5KB, which is a relatively small addition to the 1M context window.

Recommendation

Apply a workaround, such as the existing additionalContext injection, until a native solution is implemented, as it has been shown to be effective in reducing speculative searches.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#api#ssr#task chaining#parallel task#integration issue

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

claude-code - 💡(How to fix) Fix MCP tool-catalog mode — surface tool name+description without full schemas [1 participants]