writing MCP tool descriptions that get used

TL;DR

An MCP tool description is routing text: it tells the agent when to call this tool, what inputs it needs, and what comes back, in concrete terms. The formula is: what it does, when to use it, key triggers, and what it returns. Test descriptions by giving them to a real agent with a task and watching which tool it picks. Vague descriptions dont get called; precise ones do.

writing MCP tool descriptions that get used

Use this when

• You are defining tools for a new or existing MCP server
• Agents pick the wrong tool or never call yours
• You need a review checklist for tool descriptions
• You want to understand why a competitor's tools get used more

Not for this skill when

• You need general API reference docs (different audience and format)
• The tools themselves are broken (fix the tools first)
• You are writing host or client documentation (different topic)

Steps

1. Write the what in one clause. The concrete action the tool performs, starting with a verb. Expected: anyone reading it knows what happens when it is called.

Shape: "[Verb] [object] [context]."
Example shape: "Searches product documentation and returns matching articles."

1. Add the when: triggers and non-triggers. Name the situations that call for this tool and the ones that dont. Expected: agents route correctly instead of guessing.

Triggers: "Use when the user asks about [topic]."
Non-triggers: "Not for [adjacent topic]; use [other tool] instead."

1. Specify inputs and outputs concretely. What the agent must provide, what it gets back, in what shape. Expected: fewer malformed calls and fewer surprises.

Inputs: required parameters in plain words.
Outputs: what returns, including the shape (list of articles with URLs, etc).

1. Keep it under the attention budget. Aim for 2 to 4 sentences; long descriptions get skimmed and the key trigger gets lost. Expected: descriptions an agent (or human) actually reads fully.

Budget: 2 to 4 sentences, third person, no marketing fluff.
Every word earns its place or gets cut.

1. Test with a real agent. Give the toolset to an agent, assign tasks, and watch which tools get picked and whether calls are well-formed. Expected: evidence, not opinions, about what works.

Test: 5 to 10 realistic tasks, note picks and miscalls.
Rewrite the descriptions behind the miscalls, retest.

Variant phrasings

MCP tool description best practices

Verb-led what, explicit triggers and non-triggers, concrete inputs and outputs, short, tested.

Why dont agents use my MCP tools

Usually the description is vague; rewrite with the formula and test against real tasks.

How to describe tools for AI agents

Like routing instructions: when to call, what it needs, what it returns.

Why it happens

At runtime, the agent sees your tools as a list of names and descriptions and must choose; that choice is the entire UX of your server. Vague descriptions ("search functionality", "handles data") give the routing model nothing to match against, so it picks whatever is most familiar or guesses wrong. Precise descriptions work because they mirror the agent's internal task representation: verbs, objects, and conditions it can pattern-match against the user's request.

Edge cases / pitfalls

• Dont stuff keywords; routing models match on meaning, and stuffing reads as spam to human reviewers.
• Keep descriptions stable across versions; agents and hosts cache them, and churn confuses routing.
• If two tools overlap, the descriptions must draw a bright line between them, or agents will flip a coin.
• Test in the actual host your users use; routing behavior varies across models and harnesses.
• Descriptions are not the place for auth details or endpoint URLs; those belong in config, not routing text.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_E5PjkmOgpxCRdyboRGRFQw