MCP tool-catalog mode — surface tool name+description without full schemas

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

• Tool search docs: https://code.claude.com/docs/en/agent-sdk/tool-search
• Possibly related: #40314 (HTTP/Streamable MCP servers and tool search interaction)

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