MENU
You are building developer productivity tools using the Claude Agent SDK. The agent helps engineers explore unfamiliar codebases, understand legacy systems, generate boilerplate code, and automate repetitive tasks. It uses the built-in tools (Read, Write, Bash, Grep, Glob) and integrates with Model Context Protocol (MCP) servers.
After integrating a local MCP server providing code analysis tools (analyze_dependencies, find_dead_code, calculate_complexity), you verify the server is healthy and tools appear in the tools/list response. However, you observe that the agent consistently uses Grep to search for import statements instead of calling analyze_dependencies---even when users explicitly ask about ''code dependencies.'' Examining tool definitions reveals:
MCP analyze_dependencies -- ''Analyzes dependency graph''
Built-in Grep -- ''Search file contents for a pattern using regular expressions. Returns matching lines with line numbers and surrounding context.''
What's the most effective approach to improve the agent's selection of MCP tools?
Claude selects tools principally from their names, descriptions, parameter schemas, and the task context. The current description---''Analyzes dependency graph''---does not explain why the MCP tool is superior to a familiar text search. It omits the tool's scope, the circumstances in which it should be selected, and the structured information it returns.
Anthropic identifies detailed descriptions as the most important factor in tool-use performance. A strong description should state what the tool does, when it should and should not be used, what its parameters mean, and any limitations. Anthropic recommends several sentences for complex tools rather than a short generic label. (https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/implement-tool-use) The MCP connector guidance likewise states that Claude selects among available tools using their names and descriptions and that clear, specific descriptions improve selection accuracy. (https://docs.anthropic.com/en/docs/agents-and-tools/mcp-connector)
Option B makes the functional distinction explicit: Grep locates textual import statements, whereas analyze_dependencies constructs a semantic graph containing direct and transitive dependencies, cycles, and potentially unresolved references. Option A is a brittle global override. Option C removes a generally useful tool. Option D increases the number of tools and selection ambiguity, contrary to Anthropic's recommendation to consolidate related operations where practical.
Official references/topics: MCP Tool Discovery; Tool Descriptions; Tool Selection Accuracy; Tool-Surface Design.