MCP Tools Agents Can Actually Use: Design Rules for Production Servers

An MCP server that mirrors your REST API one endpoint per tool gives agents too many choices and too much output. Rules for designing tools around tasks, keeping results small, writing errors the model can act on, and why tool annotations are hints rather than controls.