A teammate added an MCP server providing a powerful analyze_codebase tool that can scan an entire repo and return structured architectural insights. But in practice, when the agent needs to find function callers or understand code structure, it almost always reaches for the built-in Grep tool instead — even when analyze_codebase would give better results.
The MCP tool description currently reads: "Analyzes the codebase."
What's the most likely cause and fix?
Why did you pick that answer? Two or three sentences. The act of articulating it is what builds the judgment — not the click that follows.
Tool selection is driven by descriptions. "Analyzes the codebase" tells the model almost nothing — it doesn't explain what kind of analysis, what inputs the tool expects, what outputs it returns, or when it's the right choice over alternatives. Meanwhile, Grep has clear semantics the model already understands deeply. The fix is to invest in the MCP tool description: explain that it returns structured architectural insights including dependency graphs, exports, and call hierarchies; give example queries it handles best; explicitly contrast it with line-level search tools like Grep. Good descriptions don't just describe the tool — they help the model decide when to choose this one.
There's no built-in bias against MCP tools. The model picks tools based on description quality and apparent fit. Forcing tool choice solves the symptom but doesn't help the model learn when this tool is appropriate — and you can't force tool choice on every relevant query manually.
The model isn't aware of tool latency and doesn't optimize for speed. This is anthropomorphizing the model's behavior. The actual issue is information, not performance.
"Always prefer MCP tools" is a blunt instruction that will cause the model to use MCP tools even when they're not the right fit. The model needs to understand when each tool applies, which is what descriptions are for. A blanket prompt rule replaces nuanced selection with crude preference.