MCP tool descriptions
A good MCP tool description states what the tool does, what it returns and when to call it (and when not to), names the API behind any free-form query, and describes every argument; both directories reject tools without one.
The description is the only thing a model reads before choosing a tool, and the first thing a reviewer reads. Both directories require one that is accurate and specific, and both reject descriptions that instruct the model instead of describing the tool.
These checks catch the missing, the too-short, the near-duplicate and the ones that never say when to use the tool.
The 11 checks
- Description says what the tool does and when to use it: Each tool description should state precisely what the tool does and when to invoke it; a missing description blocks Anthropic review, and one under about 40 characters rarely covers both.
- Every tool has a non-empty description: OpenAI requires every tool to have a non-empty description that explains its purpose and behavior, when to use it, and any limitations or side effects.
- Every argument has a description: Give every argument a description that says what it is and its format, with an example where the format matters; without one the model guesses from the name.
- Argument names are specific: Name arguments unambiguously: issue_id instead of id, user_email instead of user, so the model knows which object and format each one takes.
- Search tools can return a concise answer: Add a response_format argument with "concise" and "detailed" values (default concise) to search tools, so the model can ask for a short answer and fetch detail only when needed.
- Description says when to use the tool: Add a sentence that says when to choose the tool, and when not to ("Use this when ... Do not use for ..."), so the model can pick between similar tools.
- Sibling tools have distinguishable descriptions: When two tools have nearly the same description, the model cannot tell which to pick; say in each description what sets it apart from the other.
- Tools that create state say how long it lasts: A tool that creates a session, cart, context or other handle should say in its description how long the handle lasts, because handles outlive any single connection and the model decides whether to create one.
- Custom query tools name or link the target API: If a tool accepts free-form endpoint paths, query strings or request bodies, its description must link to or name the target API; the Anthropic checklist gives "Makes a request to the API" as a description that fails.
- List and search tools take a limit or cursor: Give list and search tools a "limit" with a sensible default and maximum plus a "cursor", and return a next cursor, so one call never floods the model’s context.
- Larger catalogs use a naming prefix: Once a server has ten or more tools, prefix their names by service or resource (for example asana_search, asana_projects_search) so a model can tell them from similar tools of other servers.
Other topics
- MCP tool annotations
- Directory review rules for MCP tools
- MCP tool names
- MCP tool input and output schemas
- Tool poisoning and hidden text
- Write-surface design for MCP tools
- MCP specification 2026-07-28: tools/list rules
Sources last verified on 2026-11-18. How findings become grades.
Check your tool list: paste your tools/list, nothing is sent anywhere