mcp-tool-design

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

Good	Bad	Why
search_issues	issueSearcher	snake_case, verb-led
get_user_by_email	user_lookup	specific over vague
create_pr_comment	comment	namespaced by object
list_repos	repos	action is explicit

Rule: <verb>_<object>[_<qualifier>]. If two tools could answer the same query, one has the wrong name.

Description Rules

Descriptions are what the model reads most carefully. Budget ~1-3 sentences:

<Verb-led action>. <When to use it / when NOT to use it>. <Any gotchas>.

Example — weak vs strong

Weak:

Creates an issue.

Strong:

Create a GitHub issue in the specified repo. Use this for new bug reports or feature requests. Do NOT use to comment on an existing issue — use create_issue_comment for that. Title is required; body supports markdown.

The "when NOT to use" line is the highest-leverage sentence you can write — it routes disambiguation without the agent needing to enumerate all tools.

Parameter Schema Rules

1. Describe every field — .describe() in Zod, Field(description=...) in Pydantic. Undescribed fields get hallucinated values
2. Use enums for closed sets — priority: z.enum(["low", "med", "high"]) beats priority: z.string()
3. Default the optional — if 80% of calls use limit=50, set the default; don't make the agent guess
4. Prefer primitives at the top level — nested objects increase hallucination rates
5. Avoid freeform "options" bags — split into discrete flags