Docs for humans vs docs for agents
Human API docs assume a reader who can google, experiment, and ask a teammate. An agent mid-conversation has none of that: your description is its entire world. The writing rules change accordingly — and "we'll reuse the OpenAPI summaries" is how you end up with agents calling delete when the user said "show".
This description is what the model's underlying function-calling layer actually reads — MCP just standardizes how it gets there. See MCP vs function calling for how the two layers split.
Seven rules for agent-grade descriptions
- Verb accuracy above all. Derive read/write from the HTTP method or GraphQL operation kind, never from the name. A query called
updateCheckreads. - Disambiguate against siblings. "Use
postsfor lists; usepostwhen you already have an id." Agents choose between tools — help them. - Concrete return shapes. "
{ items: [{ id, title, status }], next_cursor }" beats "returns the posts". Never "returns data". - Enums verbatim. Every valid value, exact casing, with meaning. An invented enum value is a guaranteed failed call.
- ID provenance. Every id argument says which tool returns it: "obtain from
list_projects.id". - Formats with examples. "ISO 8601 date, e.g. 2026-01-15. Not a timestamp." Dates are the single biggest argument-error source.
- State the side effects. Writes carry a [WRITE] marker and one sentence on what changes and whether it's reversible.
The scale problem — and the honest answer
Nobody hand-writes this for 84 tools, and nobody re-writes it after every API change. The workable pipeline is AI generation with schema guardrails: the model gets the input schema, the operation kind as authoritative, sibling tool names for disambiguation, and (when safe) a probed sample response to ground the return shape. Humans edit the 5% that needs product nuance.
Built into the conversion
FAQ
- Why do MCP tool descriptions matter so much?
- Because the agent cannot ask follow-up questions. It picks a tool, fills its arguments, and interprets the result purely from your descriptions. Every ambiguity becomes a wrong tool choice, an invalid argument, or a hallucinated claim about what happened.
- What should an MCP tool description contain?
- For agents: a verb-accurate summary (reads say 'Returns/Lists', writes are marked), when to pick this tool versus its siblings, the concrete return shape with field names, every enum value verbatim, exact date formats with examples, and where each ID argument comes from (which tool returns it).
- Can AI write MCP tool descriptions automatically?
- Yes, and it should — with guardrails: derive the verb from the HTTP method or GraphQL operation kind (never the field name), list enum values from the schema verbatim, and probe a sample response to ground the return shape. That's how Command+K generates descriptions for every converted tool.