API Evangelist Paper · Fundamentals
The MCP Style Guide
Naming, describing, shaping and governing the tools an agent reads first.
About this paper
The tool list is the first thing an agent reads. It is read on every connection, billed as tokens on every turn, and used to decide what to call. Every inconsistency in it is paid for again and again. Yet almost no MCP server has the thing every mature API has: a written style guide.
This paper is that style guide. It comes from evaluating every tool, prompt, resource and refusal on two production MCP servers, 212 tools built by one practice that still drifted apart on naming, tier labels, pagination and error shape. It measures the same things across the APIs.io catalog, 103,737 tools on 4,439 servers, and adds what providers report from running their own. The result is fifty-five rules, each tied to the evidence behind it, and a checklist you can turn into a ruleset for your pipeline.
What's inside
- Why MCP needs a style guide of its own
- How the evidence was gathered: our servers, the catalog, the provider record
- Naming
- Descriptions
- Input schemas
- Output
- Errors and refusals
- Side effects and annotations
- Context budget
- Prompts, resources and instructions
- Versioning and testing
- Anti-patterns and a provider self-assessment
- Appendix A — The rules, as a checklist
What you get for $25.00
These papers are experience-based and vendor-neutral, distilled from the API Evangelist research at apievangelist.com. Questions before buying? [email protected].
arrow_back All papers