MCP Tool Design

A well-designed tool is invoked correctly by the agent on the first try. A bad one causes loops, wrong-tool selection, or hallucinated arguments.

When to Use

• Adding a new tool to an MCP server
• Debugging "the model never picks this tool" or "the model picks the wrong tool"
• Reviewing a PR that adds tools
• Cleaning up a server with 30+ tools

The Three Levers

Agents pick tools based on name, description, and parameter schema — in that order of signal strength. Every design choice should strengthen at least one.

Naming Rules