The MCP Style Guide

An API Evangelist Paper — naming, describing, shaping and governing the tools an agent reads first

By Kin Lane, the API Evangelist · Version 1.0 · October 2026
_{Status as of October 2026. Written against MCP protocol 2025-06-18 and the 2026-07-28 revision. This paper is updated on a regular cycle.}

Executive summary

An API style guide tells humans how to name a path, shape a response and report an error. An MCP server needs the same thing, and almost nobody has written one. 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 choose what to call. Every inconsistency in it is paid for again and again.

This paper is a style guide for MCP servers. It was not written from first principles. It is built from three bodies of evidence:

• The servers API Evangelist operates. APIs.io at apis.io/mcp (144 tools, 36 prompts, four task-scoped endpoints, OAuth plus pay-per-call) and API Evangelist at mcp.apievangelist.com/mcp (68 tools, 29 prompts, three task-scoped endpoints). Every tool, prompt, resource and refusal was called and read.
• The MCP servers in the APIs.io catalog. The names of 103,737 tools across 4,439 servers from 4,432 providers, and the full definitions (descriptions, input schemas, annotations, output schemas) of a 76-server, 1,227-tool sample captured live from public endpoints.
• What providers say. Sixty-five posts about MCP from twelve providers in the API Evangelist network, with the four most substantive read in full: Axiom, Kong and two from Atlassian.

The three agree more than they differ. Our own two servers, built by one practice within months of each other, still disagree on naming, tier labels, pagination and how a refused call answers. The catalog shows the same drift at market scale: five naming styles in common use, half of all input properties with no description, and fewer than one server in three declaring structured output. That is the strongest argument for a written style guide. Without one, even a single team drifts, and a market of thousands drifts in every direction at once.

The guide is organized the way the evaluation was:

1. Naming: verbs, collisions, and the server boundary.
2. Descriptions: what a tool returns, when to use it, what it costs, what it changes.
3. Input schemas: one ID name, bounds in the schema, one pagination model.
4. Output: small by default, structured, honest about truncation, pointing to the next call.
5. Errors and refusals: a refusal an agent can act on.
6. Side effects and annotations: generated from one list, enforced by a test.
7. Context budget: task-scoped endpoints and reference text moved out of the tool list.
8. Prompts, resources and instructions: the parts of the protocol most servers skip.
9. Versioning and testing: tools cannot be deprecated quietly.

Each section closes with numbered rules. Appendix A collects all of them in one checklist you can turn into a ruleset.

1. Why MCP needs a style guide of its own

API Evangelist has argued for a long time that a style guide is the cheapest form of governance. Two pages on naming and response shape do more than a hundred lint rules nobody understands. The argument holds for MCP. The stakes are higher.

A human developer reads documentation once and remembers it. An agent reads the tool list every time it connects, in full, and makes a fresh choice each turn. Three things follow:

• Inconsistency costs tokens. A field described in prose and again in a schema is read twice. A shared argument with a sixty-word description, repeated on 68 tools, is about four thousand words the model reads before it does anything.
• Inconsistency costs accuracy. Kong’s Context Mesh announcement makes the point plainly: a large set of similar or overlapping tools makes choosing the right one harder. Names that do not follow a pattern make the agent guess.
• Inconsistency costs money. Tool definitions are billed every time they are sent. A tool list is a recurring line item for every customer that connects.

There is no special “agentic” discipline here. This is the same style-guide work that web, mobile and partner integrations always needed, finally done well enough that a machine can consume it. The difference is that the machine does not forgive what a human would work around.

Where this paper sits

Publishing a Public MCP Server covers the operational lifecycle: build, auth, curate, host, govern, distribute. MCP Documentation Beyond Reference covers the behavioral layer an agent needs: side effects, failure, consistency, sequencing. This paper covers the layer between them: the conventions for the surface itself. If the first paper is “should we ship this” and the second is “what does the agent need to know,” this one is “how should it read.”

2. How the evidence was gathered

Our own servers. Both production servers were loaded and their handlers called directly: initialize, tools/list, prompts/list, resources/list and resources/templates/list on every endpoint, plus refused and malformed calls. Token weight is the serialized tools/list response divided by four, so treat it as approximate. Two older servers were also inventoried: a two-tool route in a legacy chat service, and a seventeen-tool Cloudflare worker whose README says it was superseded before it was deployed. They matter mainly as evidence that the naming style was never written down.

The catalog. APIs.io tracks every public MCP server it can find, at mcp.apis.io. Two views of that data are used here:

• Names, catalog-wide. 103,737 tool names across 4,439 servers from 4,432 providers. Names are recorded for every server whose tool list could be read. They support findings about naming style, verbs, server size and shared names.
• Full definitions, sampled. On 2026-10-20 a probe sent only initialize and tools/list to every remote endpoint in scope, with no credentials and no tool calls. Of 2,418 endpoints, 608 answered anonymously with a tool list; 1,620 required authentication, which is itself a finding about how the market ships. The sample analyzed here is the 76 of those captures available in the shared profile store at the time of writing, an alphabetical slice, with 1,227 tools. Our own two servers are excluded from it. Read the sample’s percentages as indicative, not as a census.

Catalog findings are reported for the market as a whole. No provider is ranked or singled out.

The provider record. API Evangelist pulls provider blogs into the network as part of profiling. A sweep of the local cache found 65 posts about MCP from 12 providers, dated September 2025 to October 2026: Kong, Google, Atlassian, Okta, Red Hat, Axiom, WooCommerce, CockroachDB, BigCommerce, AWS Marketplace, RoxyAPI and Anthropic’s status feed. Most cached posts are feed excerpts, so the four with the most design substance were read in full at their source: Axiom on designing MCP servers for wide events, Kong on Context Mesh, and Atlassian on both Rovo MCP usage and building a CLI alongside an MCP server. The local cache covers a small fraction of the catalog, so these posts show what the market is raising rather than measuring how common each practice is.

The corpus. API Evangelist’s writing on style guides, governance rules, and the agentic turn supplies the frame: rules wrapped in policy, naming as the cheapest consistency, internet standards over house conventions.

3. Naming

Naming is the cheapest consistency there is, and the place teams resist hardest. Teams will spend far more effort arguing against a rename than the rename would cost. With tools the cost of not renaming is paid by every agent on every connection.

What the evaluation found

Most of the 212 tools follow verb_noun with a useful split: find_ means search or browse and returns a page, get_ means fetch one thing by its identifier. APIs.io has 45 find_ and 40 get_ tools. API Evangelist has 15 and 17. That split is worth keeping. It tells the agent the shape of the answer before it calls.

The exceptions are where the cost shows:

• Noun-first names. cohort_stats, cohort_rankings, tag_group_tags, vc_portfolio, company_peers, entity_demand, api_scorecard. These do not say whether they search or fetch.
• Questions as names. whats_changed, what_can_i_fix. Readable for a person, but they break the pattern an agent is using to sort the list.
• Three verbs for “list.” find_tags, list_watches and cohort_rankings all return lists. The distinction worth keeping is narrower: list_ for the caller’s own items, find_ for the catalog.
• The brand on either end. apis_io_search on one server, search_api_evangelist on the other. submit_feedback on one, submit_api_evangelist_feedback on the other.
• A tool and a prompt with one name. story_leads is both on APIs.io.
• Case. The superseded worker used kebab-case (get-posts-feed). The production servers use snake_case. Nobody decided; it happened.

What the catalog shows

Across 103,737 tool names, snake_case leads but does not rule:

228 servers mix more than one style within the same tool list.

The verbs tell a clearer story. get opens 26,354 names and list 10,182, followed by create (7,855), update (4,248), delete (3,512) and search (2,496). The CRUD vocabulary of REST carried straight over. So did HTTP itself: 2,787 tools across 315 servers are named after an HTTP method (post_, put_, patch_), the mark of a server generated from an OpenAPI without renaming. An agent does not know what post_orders_id_items does any better than a developer would.

Read verbs multiply. A quarter of servers (1,048 of 4,439) use three or more different verbs to mean “read” — get, list, fetch, retrieve, search, query, find, lookup — in the same tool list.

Size spreads widely. The median server exposes 12 tools. One in ten exposes more than 50, 171 expose more than 100, and the largest exposes 588.

Shared names are not always a problem. The most common names in the catalog are search_catalog (217 servers), create_checkout (191) and create_cart (188). They come from a shared commerce protocol that 185 servers implement, and 99 servers share one website platform’s generated tool set. When the name is a published standard, sharing it is the point. When it is a coincidence, it is a collision.

Collisions across servers

Nine tool names exist on both servers: company_gaps, find_areas, find_company_insights, find_tags, get_area, get_company_insight, get_tag, insights_adoption and insights_dimensions. A client connected to both sees duplicates and has to choose by description. Some of them are not the same tool:

• find_areas describes different things on each server.
• insights_adoption is free on one server and priced at five cents a call on the other.
• find_company_insights takes an industry filter on one and not the other.

A name is a promise. When two tools share one, an agent will assume they are interchangeable. If they are not, the agent will be wrong about cost, about parameters, or about what comes back.

Rules

• N1. Name tools verb_noun in snake_case. Write the convention down.
• N2. Reserve a small set of verbs with fixed meanings. find_ searches and returns a page. get_ returns one item by identifier. list_ returns the caller’s own items. create_, update_, delete_ change state. Add verbs deliberately, not one tool at a time.
• N3. Never reuse a tool name across your servers unless the meaning, schema and tier are identical. If they are, it should be the same code. When a shared protocol defines a tool name, use it exactly.
• N4. Put a server-specific word in the same position everywhere, or nowhere.
• N5. Never give a prompt and a tool the same name.
• N6. Name for the task, not the endpoint. Axiom’s guidance is to design the tool list around real use cases rather than wrapping REST endpoints one to one. Never ship an HTTP method as a verb.

4. Descriptions

The description is the tool’s documentation, its sales copy and its safety notice in one field. It is the text the model actually reasons over when it picks a tool.

What good looks like

The best descriptions in the evaluation do four things:

• Say what comes back, and how to keep it small. get_provider explains that heavy sections are left out by default and that fields=["score"] returns only the rating.
• Say when the answer is partial. find_operations says it reports in meta.query.truncated when more matched than were read.
• Say what the call changes, and what happens next. claim_listing says it returns 202 with a token, that a person verifies it and emails the owner, that there is nothing else to call, and that check_status tracks it.
• Say when to use it. get_overview says to start there. get_prices says to call it before budgeting a run of paid tools.

Where it drifts

Tier labels are the clearest example. On APIs.io, 65 tools open with a capitalized tier word, 11 mention their plan somewhere mid-sentence, and 56 carry no marker. On API Evangelist, 8 tools open with “PRO —”, 2 end with “Pro.”, 9 say “Free.” and 49 say nothing. Two of the gated governance tools never mention that they are gated, although the server instructions say that work is paid. One tool is labelled “Pro.” but is freemium by design: a free preview with a paid full answer.

An agent planning a task reads those labels to decide what it can afford. A missing label reads as free. A label that overstates a gate stops an agent from making a call it was allowed to make.

Length varies too. The median APIs.io description is 348 characters and the longest is 1,275. The median API Evangelist description is 152. Neither is wrong. Long descriptions are fine when every sentence earns its tokens, and APIs.io shows the fix when they do not: long parameter reference moved into a resource at apis://docs/tools/{name}, with one line in the description pointing to it. find_providers alone had been carrying about 2,700 tokens of reference before that move.

What the catalog shows

In the 1,227-tool sample, descriptions are substantial: a median of 335 characters, with one in ten over 880, and almost none empty. Length is not the gap. Content is:

The price figure reflects how many agent-commerce and pay-per-call servers answer tools/list without a login, so treat it as a ceiling. The “when to use it” figure is the one to act on. Nearly nine tools in ten leave the agent to work out from the name alone which neighbor it should have called instead.

Rules

• D1. Open with one sentence that says what the tool returns.
• D2. Say when to use it, especially relative to its neighbors (“use find_ to search, get_ once you have a slug”).
• D3. State every side effect. If nothing changes, the annotations say so; the description does not need to.
• D4. Start every gated tool’s description with one fixed tier token, generated from the same list that enforces the gate. Never type a tier label by hand.
• D5. The label matches the gate. A freemium tool says “free preview; full answer on X.”
• D6. Tell the agent how to keep the result small: projection, views, limits.
• D7. Move long reference into a resource and link it in one line.
• D8. Never contradict the schema in prose. If a bound or default changes, the description should not have to.

5. Input schemas

What good looks like

The strongest pattern in the evaluation is the identifier described by where it comes from: “Provider slug — lowercase, hyphenated, as find_providers returns it, e.g. stripe.” That one line tells the agent the format, the source and an example. APIs.io declares 98 enums with defaults where they matter (view is summary or full; match is any or all). Only two of its properties lack a description; API Evangelist has none. A missing required argument gets an error that names the argument and shows a corrected call.

Where it drifts

• Prose and schema disagree. One tool declares maximum: 50 for limit and describes it as “1–100”.
• Defaults live in prose. There are seven different shapes of limit on one server. Some declare a default; some only say “default 25” in the description.

• Enums written as text. A band field lists its values in prose (“exemplar	strong
  developing	thin	minimal”) instead of an enum.

• One entity, many names. On APIs.io an identifier is passed as slug, id, aid, provider or name depending on the tool. API Evangelist uses slug throughout.
• One input, two names. On the governance tools, the API under review is document on one tool and api on the next, and the schema allows arbitrary extra properties.
• Two paging models. APIs.io pages with page and limit on 55 tools and a cursor on 2.
• A shared argument that costs too much. Both servers inject an optional context argument on every tool. The wording differs: about sixty words on one server, a sentence on the other. Multiplied across every tool, the long version is one of the larger costs on the list.

What the catalog shows

The sample’s 1,227 tools declare 5,434 input properties.

At the tool level, 635 of 1,227 schemas (52%) set additionalProperties: false.

Half of all arguments arrive with nothing but a name. Defaults are rare in the schema and common in prose. Paging arguments, where they exist, use six different names: limit (107), page_size (16), page (15), offset (6), cursor (4), per_page (3) and after (2).

Rules

• S1. One argument name per entity across the whole server. Describe where its value comes from, with an example.
• S2. Defaults, bounds and allowed values go in the schema: default, minimum, maximum, enum. Prose may explain them, never restate them differently.
• S3. One pagination model per server. A cursor is the safer default for anything that can change between calls.
• S4. Name the same input the same way on every tool that takes it.
• S5. additionalProperties: false unless the tool genuinely accepts open input, and say so when it does.
• S6. Keep injected arguments short. Anything added to every tool is paid for on every tool.
• S7. When a required argument is missing, return an error that names it and shows a correct call.

6. Output

The provider record has more to say here than anywhere else, and Axiom says the most. Its guidance is to make responses useful, predictable and small by default, and it puts numbers on that:

• Tables returned as a header row plus value rows, instead of repeated-key JSON, cut tokens by about 29% in their example.
• One cell budget per response. Summary tables fill first; the rest is shared across data tables.
• Every trimmed table says how many rows are shown and how many exist.
• Limits are pushed into the query, not applied after serializing everything.
• Time windows default narrow and recent. Histograms default to about 15 buckets; 100 buckets was more than six times larger.
• Clients can raise the budget explicitly, for example through a server URL parameter, when a model with a large context window can use more.

Atlassian adds the other half. Agents grounded in pre-mapped relationships gave more accurate answers on fewer tokens than agents rediscovering those links through separate calls. Its CLI experiment found that putting the follow-up command in the search output meant agents stopped re-reading documentation to work out what to do next.

What the evaluation found

Our servers already do several of these things. view and fields projection keep results small. meta.query.truncated reports a partial answer in a fixed place. Six APIs.io get_ tools return a next block that lists the sub-resources that exist and the exact tool call that fetches each, which callers can switch off with include_next=false. That is the same lesson Atlassian reported, arrived at independently.

The gap is structure. None of the 212 tools declares an outputSchema or returns structuredContent. Every result is JSON serialized into a text block. The protocol has supported structured output since 2025-06-18. Without it, the client cannot validate the result, and the agent has to parse text the server already had as data.

The catalog is further along than we are, and still early. In the sample, 285 of 1,227 tools (23%) declare an outputSchema, on 22 of 76 servers (29%). Structured output is the clearest place where a convention exists in the protocol and most of the market has not adopted it yet.

Rules

• O1. Small by default. Ship summary views, field projection and row limits, and push limits into the query.
• O2. Report truncation in a fixed field, with counts shown and counts available.
• O3. Declare outputSchema and return structuredContent, with the text block as a fallback.
• O4. Return the next step as an exact tool call, and let callers switch it off.
• O5. Return related context the agent will need, when you already have it.
• O6. Prefer compact shapes for tabular data. Repeated keys are paid for on every row.
• O7. Link back to the human page for the same entity. A person will ask to see it.

7. Errors and refusals

A refused call is a moment of truth for a paid MCP server. The agent has to understand what happened, tell its user why, and decide what to do next. Most servers return something an agent cannot act on.

What the evaluation found

The two servers fail in completely different ways.

APIs.io returns a JSON-RPC result with isError: true and the HTTP status in _meta. The body names the plan required, the price in dollars, the pricing band and the plans page. It gives an agent-actionable route (pay five cents in USDC over x402 and retry this exact request) and a human handoff, a URL the agent can show the person it works for. It even explains why it is shaped that way: an MCP tool result cannot carry an HTTP challenge, because the error travels inside a JSON-RPC 200.

A tool called on the wrong endpoint gets the same care. The answer says the tool is not in this toolset and lists the endpoints that serve it.

API Evangelist, for an anonymous caller on a gated tool, returns an HTTP 401 with a WWW-Authenticate header and the body {"error":"unauthorized"}. No plan is named and no price is given. The prose upgrade message exists, but only older clients see it. The APIs.io production test suite has a status for exactly this response, a refusal that names no plan, and the API Evangelist server has no equivalent suite to catch it.

The HTTP 401 is correct for starting OAuth, and it has to stay. The rule is that the agent should never be left with only that.

This matters at catalog scale. When the 2026-10-20 probe asked 2,418 public MCP endpoints for their tool lists without credentials, 1,620 (67%) required authentication before showing anything at all. Those servers were described to an anonymous agent entirely by their refusal. A refusal that names what the server does and how to get in is the only description such a server has.

Rules

• E1. Tool failures return a result with isError: true, not a transport error, unless the failure is authentication that the client must handle at the transport.
• E2. A paywall refusal names the plan, the price, where to upgrade, and any route the agent can take itself, plus a URL for the human.
• E3. Map internet standards into the result. Carry RFC 9457 problem-details fields (type, title, detail, status) rather than inventing a house error shape.
• E4. A tool on the wrong endpoint answers with the endpoints that serve it.
• E5. Validation errors name the argument and show a corrected call.
• E6. Every refusal shape is in a production test, per plan.

8. Side effects and annotations

Atlassian reports that about one third of the five million tool calls its Rovo MCP server handles each working day are writes. Write design is not an edge case. Annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) are how a client decides what to confirm with a person and what to run without asking.

What the evaluation found

APIs.io derives annotations from four central sets (write, destructive, idempotent, open world), generates a title for every tool, and checks all of it in a test. The result is honest: 125 read-only tools, 12 writes, 3 idempotent writes, 3 idempotent deletes and 1 open-world tool. Its owner-side writes follow one pattern, stated in the instructions and repeated in each tool: the call returns 202, a person works it, nothing is published on the caller’s behalf, and a tracking tool reports progress.

API Evangelist marks 66 of 68 tools read-only, with one open-world tool and one write. One tool issues a tamper-evident certificate and is marked read-only. If issuing records anything, that hint is wrong. No read tool on that server sets idempotentHint.

Across the catalog sample, annotations are common but incomplete. 738 of 1,227 tools (60%) carry some annotation, and 693 (56%) carry a title. 51 of 76 servers annotate at least one tool; 39 annotate every tool. Of the four hints, readOnlyHint is set most often (728 tools) and idempotentHint least (451). 115 tools declare themselves destructive. The servers that annotate everything tend to generate annotations; the ones that annotate some tools tend to have typed them.

Rules

• A1. Every tool carries a title and all four hints. None is left to default.
• A2. Hints are generated from central lists, not typed per tool, and a test fails if a tool is missing from the lists.
• A3. Anything that creates, issues, records or sends is not read-only.
• A4. Write tools that need human judgment return 202 and a tracking tool, and say so.
• A5. Support multi-step writes in one call where the steps always travel together. Atlassian made this native after seeing its write share.

9. Context budget

The full APIs.io tool list is about 46,700 tokens. The full API Evangelist list is about 18,900. That is paid before the user’s question is read.

The provider record agrees on the direction. Kong argues against one tool per operation at enterprise scale: an API with 200 operations becomes 200 tool definitions the model processes when it needs one. Its answer is search, load the schema, then execute. Axiom puts a minimal core toolset on by default and specialized families behind flags. Atlassian found that agents preferred a CLI to its MCP server once both existed, and that the CLI cut tokens and time per task by about 8%. Its point was not that MCP is wrong. It was that the whole task should be measured, startup cost included, and that every surface should call the same handlers so none of them drift.

Google’s API Gateway and Apigee posts show the other side: annotate an OpenAPI and the operations become tools at the gateway, governed by the auth, quotas and logging already in place. This works for small and medium surfaces, and it inherits whatever quality the OpenAPI already has.

What the evaluation found

Both servers already publish task-scoped endpoints. APIs.io’s four run from about 10,700 to 15,700 tokens. API Evangelist’s three run from about 5,600 to 10,000. The server instructions advertise them with tool counts and send the agent to the lighter one for single kinds of work. The heaviest single tools are search and filter tools with many parameters, between roughly 600 and 1,150 tokens each.

The catalog shows how wide the range is. In the sample, the median server’s tool list weighs about 4,300 tokens. One in ten weighs more than 47,000. Twelve of 76 cross 20,000, and the largest is about 214,000 tokens, more than many models can hold before the user says anything. Catalog-wide, 171 servers expose more than 100 tools. The median is healthy. The tail is where a style guide’s context rules earn their place.

Two cautions about our own servers. One advertised count was wrong: an endpoint claimed 39 tools and listed 37 to ordinary callers, because two hidden admin tools were counted. And the scoped sets overlap, which is intended, but it means a client connecting to more than one sees duplicates.

Rules

• C1. Measure the token weight of every endpoint, and publish it.
• C2. Offer task-scoped endpoints once the full list crosses a budget you set. A full list over about 20,000 tokens is a strong signal.
• C3. Compute advertised counts from what the caller is actually shown.
• C4. For large surfaces, prefer search, describe, execute over a tool per operation.
• C5. Keep reference text out of the tool list (D7).
• C6. If you ship a CLI or SDK beside the server, generate both from the same handlers.

10. Prompts, resources and instructions

Most servers ship tools and nothing else. Prompts, resources and server instructions are where a provider tells the agent how the tools fit together.

What the evaluation found

• Prompts as journeys. API Evangelist’s 29 prompts map to four journeys: research, check an API for free, make one agent-ready, govern at scale. Every prompt is listed to every caller and gated only when used, and each carries whether it is paid.
• Resources as attachable twins. apis://provider/{slug}, apis://provider/{slug}/openapi, ae://post/{slug} and similar templates let a client attach an entity as context instead of calling a tool for it.
• Prices as a resource. apis://prices and get_prices return the same price map the pay-per-call path and price headers use. An agent can budget before its first refusal.
• Instructions that do real work. Both servers open with scope, advertise the lighter endpoints, name the first call, map prompts to journeys and state the tier boundary in plain words. APIs.io also states the read/write contract and names the free tools that are never metered. Counts are computed from the tool table. A parity test exists because the instructions once still described the server as read-only discovery on the day fifteen write tools landed.

Rules

• P1. Ship prompts for the main journeys, with minimal required arguments.
• P2. Offer a resource template for every entity an agent would want to attach.
• P3. Publish prices as a resource from the same source that bills.
• P4. Instructions name the first call, the scoped endpoints, the journeys, the tier boundary and the read/write contract.
• P5. Generate every number in the instructions from the server itself.

11. Versioning and testing

MCP’s own deprecation policy carries a twelve-month window and a required migration path. Providers should hold themselves to the same standard. A listing can be deprecated. A tool cannot be deprecated quietly, because agents and saved workflows call it by name.

What the evaluation found

Both servers report a serverInfo version (1.3.0 and 1.2.0). No changelog tied to those versions was found. Both publish generated server cards and server.json for registries.

Testing is uneven in the same way as everything else. APIs.io has seven MCP test files: annotations, toolsets, toolset logging, price bands, skills, feedback, and a surface-parity test that compares the MCP tools to the published OpenAPI. A daily customer test runs about 1,280 production checks per plan and classifies results as leaks, wrongful refusals, refusals that name no plan, HTML error pages and residue. No equivalent was found for the API Evangelist server.

Rules

• V1. Version the server, and keep a changelog that names added, changed and removed tools.
• V2. Renaming a tool is a breaking change. Keep the old name as an alias, mark it deprecated in its description, and set a removal date.
• V3. Test that the MCP surface matches the API contract it wraps.
• V4. Run a production test per plan that checks every tool’s success and refusal shapes.
• V5. Read transcripts, not only pass rates. Atlassian found agents ignoring instructions and reading source files, which no score flagged.

Anti-patterns worth watching for

• The unwritten convention. A team that agrees on style in conversation drifts within months. Two servers built by one practice prove it.
• The shared name with a different meaning. Two tools called the same thing will be treated as the same thing.
• The hand-typed tier label. It will fall out of step with the gate. Generate it.
• The prose bound. A limit stated in a description and declared differently in the schema.
• The bare 401. Correct for the transport, useless to the agent and its user.
• JSON in a text block. The server had structure and threw it away.
• The endpoint dump. Every operation as a tool, with every tool’s reference text inline.
• The read-only write. A tool that records something and says it does not.
• The silent rename. A tool that disappears because someone tidied the list.

Provider self-assessment

Answer these against your own server. Each “no” is a rule in Appendix A.

1. Is your naming convention written down, with a fixed meaning for each verb?
2. Does any tool name appear on two of your servers with different meaning, schema or tier?
3. Does every description open with what the tool returns?
4. Are tier labels generated from the same list that enforces the gate?
5. Is there one identifier name per entity, and one pagination model per server?
6. Are every default, bound and allowed value declared in the schema?
7. Do your tools declare outputSchema and return structuredContent?
8. Is truncation reported in a fixed field with counts?
9. Does a refused call name the plan, the price and a route forward for both agent and human?
10. Are annotations generated centrally and checked by a test?
11. Do you know the token weight of every endpoint you publish?
12. Do your instructions name the first call, and are their numbers computed?
13. Do you keep a changelog of tools, and treat a rename as breaking?
14. Do you test the MCP surface against the API contract, per plan, in production?

Where this is going

The protocol is filling in the gaps style guides cover today. Structured output is already in the spec. Axiom has proposed budget hints, paging hints and a standard block that records which caps were applied. The 2026-07-28 revision made stateless servers practical, which changes how pagination and long tasks should work. Each of these will turn a house convention into a protocol feature.

What will not change is the need to write the convention down. An API style guide became useful the moment it became a ruleset a pipeline could run. The same is happening for MCP: the API Commons validator already lints MCP servers alongside OpenAPI, and the rules in Appendix A are written so each can become one. A style guide that only lives in prose drifts. A style guide that runs in the pipeline holds.

The evaluation behind this paper found real drift in servers built by people who care about this. That is the honest finding, and the useful one. The fixes are small, mostly mechanical, and the same for everyone.

Appendix A — The rules, as a checklist

Appendix B — Sources

Servers evaluated

Catalog data

Provider writing read in full

• Axiom — Designing MCP servers for wide events — https://axiom.co/blog/designing-mcp-servers-for-wide-events
• Kong — Context Mesh — https://konghq.com/blog/product-releases/context-mesh
• Atlassian — Inside Rovo MCP usage — https://www.atlassian.com/blog/company-news/inside-rovo-mcp-usage
• Atlassian — Giving AI agents design system context from the terminal — https://www.atlassian.com/blog/ai-at-work/giving-ai-agents-design-system-context-from-the-terminal-what-we-learned-building-a-cli

Provider writing surveyed (feed excerpts in the API Evangelist network): Google on API Gateway and Apigee hybrid MCP support, stateless MCP, and DPoP for OAuth; Kong on MCP access control, registries, metrics and AI Gateway; Okta on Cross App Access for MCP clients; Red Hat on its MCP gateway for OpenShift; WooCommerce on canonical abilities; RoxyAPI on grounding-layer design.

Every provider named here is profiled at APIs.io, and their public MCP servers are tracked at mcp.apis.io.

About API Evangelist

API Evangelist is the research, analysis, and advisory practice of Kin Lane, studying the business and politics of the API industry since 2010. For sixteen years it has been one of the most cited independent voices in the space, publishing open research at apievangelist.com and maintaining a working catalog of the API landscape at APIs.io — including the MCP server directory at mcp.apis.io and the two MCP servers evaluated in this paper.

The practice is deliberately independent and vendor-neutral. Kin is a former Presidential Innovation Fellow and has advised platform teams, enterprises, and government agencies on API strategy, governance, and developer experience. The method is consistent: survey what providers actually ship, define it as open, machine-readable artifacts (OpenAPI, APIs.json, and now MCP), and turn that evidence into guidance practitioners can act on. This paper is a direct product of that method.

About API Evangelist White Papers

API Evangelist White Papers are formal, practitioner-focused guides distilled from ongoing research across the API landscape. Each one takes a single, consequential shift in API operations — like writing a style guide for the tools an agent reads — and turns a broad scan of how real providers handle it into an opinionated, reusable playbook, complete with anti-patterns and a self-assessment you can run against your own operations.

They differ from a typical blog post or vendor white paper in three ways:

• Evidence-based. Every recommendation is grounded in what providers actually shipped, cross-referenced to the live catalog at APIs.io.
• Vendor-neutral. No sponsor steers the conclusions; tools and platforms are named on merit.
• Living documents. Each paper carries a version and an “as of” date, and is revised on a regular cycle as the landscape moves — you have access to a maintained reference, not a frozen PDF.

White papers are distributed to a select group of API providers and teams. If you’re reading this, you’re part of that group.

API Evangelist Services

This paper is a map; API Evangelist also does the work alongside you. Engagements draw on the same research practice behind these papers and are organized into three areas of work — discovery, governance, and evangelism. Each area is made up of focused, repeatable engagements you can mix and match to define what your business needs, operate it in consistent ways, and tell the story of the work as it happens. Most start with a single conversation about your priorities.

• Discovery — map the words, interfaces, and standards that define what your operations actually need before anything gets built: Vocabulary (the terms that define what is needed), Interfaces (mapping existing commercial or open-source interfaces and developing new ones — your OpenAPI and now your MCP server), and Standards (the standards required for interoperability).
• Governance — define and iterate upon the Strategies, Experiences, Policies, Rules, Pipelines, Skills, and Reviews that make your operations consistent, compliant, and repeatable — including turning an MCP style guide like this one into machine-enforceable rules.
• Evangelism — craft and publish the Stories, Conversations, Talks, Research, Papers, and Workshops that tell the story of your work at the intersection of people and interfaces — the same practice that produced this paper.

Get in touch

If you’d like to go deeper on anything in this paper — an evaluation of your MCP server against these rules, a ruleset built from your own style guide, or a broader API strategy engagement — API Evangelist welcomes the conversation.

• Email: [email protected]
• Web: apievangelist.com · Services: services.apievangelist.com
• Catalog: APIs.io · MCP directory: mcp.apis.io

— Kin Lane, the API Evangelist

_{© API Evangelist · Kin Lane · This paper is part of a regularly-updated series.
The server evaluation behind this paper lives alongside it in the API Evangelist research archive.}