[FEATURE] MCP tool preference / priority configuration

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

When an MCP server provides tools that are superior replacements for built-in tools (e.g., a pre-indexed code search vs Grep/Glob), there's no way to tell Claude to prefer the MCP tool. The built-in system prompt instructs Claude to "use Grep for content search" and "use Glob for file search," and Claude internalizes these as defaults. MCP tool descriptions can include "USE THIS INSTEAD OF grep" hints, but these compete with the built-in guidance rather than replacing it.

We maintain a codebase indexer MCP server that provides semantic code search (find definitions, references, implementations) via pre-indexed SQLite lookups — typically 100-5000x faster than grep with zero false positives. Despite investing heavily in multiple guidance layers, Claude still defaults to Grep/Glob a significant amount of the time, requiring runtime hook intervention to redirect.

Proposed Solution

Add a toolPreferences configuration in settings.json that lets users declare MCP tools as preferred replacements for built-in tools:

{
  "toolPreferences": {
    "mcp__indexer__find_definition": {
      "preferOver": ["Grep", "Glob"],
      "when": "searching for symbol definitions within indexed projects"
    },
    "mcp__indexer__find_references": {
      "preferOver": ["Grep"],
      "when": "searching for symbol usages within indexed projects"
    },
    "mcp__indexer__find_file": {
      "preferOver": ["Glob"],
      "when": "finding files by name within indexed projects"
    }
  }
}

When Claude considers using a built-in tool (Grep, Glob, Bash grep/find), the system prompt would check if an MCP tool is configured as preferred for that use case and route accordingly — at tool selection time, not after execution.

The when field provides natural-language scoping so the preference only applies in relevant contexts (e.g., "within indexed projects" — Grep/Glob remain available for paths outside the index).

Alternative Solutions

We currently use four layers, all of which work but are fragile:

1. CLAUDE.md instructions — A prominent table mapping tasks to MCP tools ("Where is X defined?" → find_definition, NOT Grep "class X"). These are additive instructions processed after the built-in system prompt, so they compete with rather than replace the default Grep/Glob guidance.

1. MCP tool descriptions — Every search tool includes "USE THIS INSTEAD OF: grep/glob" with specific speedup numbers (e.g., "⚡ 150-5600x faster with ZERO false positives"). Effective for the main conversation but not seen by subagents until they load MCP tools.

1. PreToolUse hooks — A shell script that intercepts Grep/Glob/Bash calls targeting indexed projects and blocks them with a message suggesting the MCP alternative. This is enforcement rather than guidance — it adds friction (block → read error → retry with MCP tool) and still consumes a tool call round-trip.

1. Agent preamble — A markdown file injected into subagent prompts via a PreToolUse hook on the Agent tool. Covers the subagent gap but requires manual wiring and hook enforcement to ensure inclusion.

Each layer has a different failure mode: CLAUDE.md can be outweighed by the built-in prompt, tool descriptions aren't visible until tool discovery, hooks add latency and friction, and preambles require enforcement. A native preference mechanism would replace all four with a single, authoritative configuration.

Priority

High - Significant impact on productivity

Feature Category

CLI commands and flags

Use Case Example

1. User asks: "Where is handleRequest called?"
2. Claude's built-in guidance says: use Grep for content search → Claude reaches for Grep "handleRequest"
3. Current behavior: PreToolUse hook blocks the Grep call, returns an error message suggesting find_references("handleRequest"), Claude retries with the MCP tool — 3 tool calls consumed for a 1-call task
4. Desired behavior: toolPreferences config tells Claude at selection time that find_references is preferred over Grep for symbol usage search → Claude calls find_references("handleRequest") directly — 1 tool call, no friction

Beyond the wasted round-trip, the Grep result would also be qualitatively worse: it matches the string "handleRequest" in comments, log messages, string literals, and unrelated variables with the same name. The MCP tool resolves references semantically through imports — it returns only actual call sites with zero false positives.

Additional Context

• The MCP protocol has tool annotations (readOnlyHint, destructiveHint, openWorldHint) that influence safety behavior, but nothing for selection priority. A toolPreferences config in settings.json would be complementary — user-configurable and local, no spec changes needed.
• Disabling built-in tools entirely is too coarse: Grep/Glob are still needed for paths outside indexed projects, non-code content (logs, config values, prose), and directories excluded from the index.
• This pattern likely applies to any MCP server that provides specialized replacements for general-purpose built-in tools (e.g., a database MCP that's better than Bash psql, a docs MCP that's better than WebFetch).