MCP Tool Design Best Practices
A server works when the model can call it. It's useful when the model picks the right tool, fills in the right arguments and recovers when something goes wrong. That depends almost entirely on how the tools are written. These guides come from building and running thousands of MCP tools.
Names and descriptions
Name MCP tools and write their descriptions so the model picks the right one, using the spec's naming rules and a before and after server.
Tool input schemas
Define MCP tool parameters that models fill in correctly, with types, enums, defaults, optional fields and nested objects, tested in Python and TypeScript.
Tool annotations
What the four MCP tool annotation hints mean, the defaults that catch people out, how Claude, VS Code and ChatGPT use them, and how to test them.
Tool errors
Return MCP tool errors the model can act on, with isError results in Python and TypeScript, and when to use a JSON-RPC protocol error instead.
Tool outputs
What an MCP tool can return: text, structured content with an outputSchema, paged results and resource links for large data, with tested examples.
How many tools
There's no fixed number. Learn the limits in VS Code, Claude Code and Cursor, and how to merge, scope and split tools so the model picks the right one.