[BUG] [Tool Routing] Deferred MCP tools lack descriptions in ToolSearch, causing Skills with overlapping capabilities to always shadow them

Status Open
Maintainer reply None cached
Activity 0 comments · opened Oct 13, 2026

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?

  1. 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.
  1. 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

  1. Configure an MCP server in claude_desktop_config.json / Claude Code config (e.g. @playwright/mcp).
  2. Install a Skill that handles the same domain (e.g., agent-browser or a browser CLI skill).
  3. 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."
  4. 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_

View original on GitHub ↗