mcp-tool-designlisted

# MCP Tool Design ## Purpose An MCP server's tools are the API the model reasons over, its quality decides whether the agent uses the server well or thrashes. The failure mode is not usually a bug; it is **too many thin, ambiguous tools with loose schemas**, which burn context, invite wrong calls, and hide destructive actions behind innocent names. This skill is the design discipline: few powerful tools, complete schemas, honest annotations, safe errors, bounded output. ## Tools vs resources vs prompts | Primitive | For | Example | |---|---|---| | **Tool** | an **action** the model invokes (may have side effects) | `create_issue`, `run_query`, `search_docs` | | **Resource** | **readable content** addressed by URI, app-controlled | `file://…`, `db://schema`, a document the host attaches | | **Prompt** | a **user-initiated** templated workflow | a `/summarize-pr` slash command | Do not model a read as a destructive tool, or a user workflow as an always-on tool. Picking the right primitive removes whole classes of misuse. ## Few, powerful tools - Prefer one `search_orders(status?, customer?, since?)` over `list_orders` + `filter_by_status` + `filter_by_customer`. Each extra tool is permanent context cost and another way to be called wrong. - A powerful tool has a **clear verb-noun name**, does one coherent job, and exposes its variations through **parameters**, not through sibling tools. - If two tools are almost always called in sequence, consider merging them; if one tool h