[BUG] [Tool Routing] Deferred MCP tools lack descriptions in ToolSearch, causing Skills with overlapping capabilities to always shadow them
Preflight Checklist
- [x] I have searched existing issues and this hasn't been reported yet
- [x] This is a single bug report (please file separate reports for different bugs)
- [x] I am using the latest version of Claude Code
What's Wrong?
When an environment mounts both a deferred MCP server (e.g. @playwright/mcp) and a Skill with overlapping capabilities (e.g. agent-browser), Claude Code always chooses the Skill and ignores the MCP server.
This happens because the deferred MCP server only appears as a bare name in ToolSearch's <available_deferred_tools> (e.g., mcp__playwright, with zero description), whereas the Skill in <available_skills> has a rich description full of trigger keywords and is paired with a blocking requirement (MUST call the Skill tool BEFORE...).
Once the multi-hundred-line SKILL.md is loaded into context, in-context anchoring prevents the model from ever falling back to MCP. For a simple browser task, this degraded execution time from 2m36s (clean MCP run) to 8m19s (shell scripts + diagnostic retries via Skill).
What Should Happen?
ToolSearch's<available_deferred_tools>should include a concise 1-sentence server-level description alongside the server name (e.g.,mcp__playwright: Browser automation for navigating pages, clicking elements, and capturing snapshots).
- Since a workspace rarely mounts more than 1–5 MCP servers, adding this costs <150 tokens total while giving the model fair semantic context to route between MCP and Skills.
- The skill invocation prompt should allow the model to prioritize existing structured MCP tools when direct tool calling is more appropriate than running multi-step CLI workflows.
Error Messages/Logs
Steps to Reproduce
- Configure an MCP server in
claude_desktop_config.json/ Claude Code config (e.g.@playwright/mcp). - Install a Skill that handles the same domain (e.g.,
agent-browseror a browser CLI skill). - Ask Claude Code: "Open https://www.tju.edu.cn/, click the search icon in the top right, search for '本科生', and list the top 5 results."
- Observe that Claude Code automatically triggers the Skill instead of loading the MCP tool schema via
ToolSearch, resulting in much slower execution (8m19s vs 2m36s).
Claude Model
None
Is this a regression?
I don't know
Last Working Version
_No response_
Claude Code Version
1.0.123
Platform
Anthropic API
Operating System
Windows
Terminal/Shell
Windows Terminal
Additional Information
_No response_