Tool Descriptions Are Protocol: 7 Key Questions in MCP Tool Design

When a model decides whether to call the tool you've published, it has exactly three things in hand: the name, the description, and the parameter schema. The README, the docs site, the code comments—none of these are in the model's context. This fact fundamentally changes what a tool description should contain.

Silent failures are what cost you

A tool that crashes is cheap: you get an error code, an exit status, and a line number. What's genuinely expensive are the failures where the model made a "reasonable" decision based on the information it had:

• The model never called the tool, because nothing in the description said when it should be called;
• The model called the tool on inputs it doesn't apply to, because the description didn't say what the tool does not cover;
• The model crammed three options into a single parameter, because the schema only said string;
• The model re-called after a timeout, because the description never mentioned that a retry means a new paid invocation.

None of these failures throw an exception. They produce a plausible-looking answer with the wrong tool, and you may only stumble onto them weeks later. The fix point is almost never in the code—it's in the fields the model can actually see.

What each field should carry

Field	The question it answers for the model	What belongs there	What usually ends up there
name	What is this, in one word?	Verb + object	Internal codename
opening of description	When should it be used?	Trigger conditions, first sentence, no preamble	"This tool allows you to…"
negative part of description	When should it not be used?	The nearest task it doesn't fit	Nothing
mechanics in description	What happens after the call?	Latency, cost, retry rules, where the result shows up	Feature list
parameter descriptions	What is a valid shape?	Units, required or not, one value per field	Restating the parameter name
annotations	Can I call it freely?	readOnlyHint, idempotentHint, openWorldHint—filled in truthfully	Omitted, or wishfully set to "true"
output schema	What comes back, in what shape?	Field names, types, which are always present	Missing, leaving the model to guess

Every row is a question the model has no other way to answer. If a row is empty, you haven't made a choice—you've handed the decision over to sampling.

MCP (Model Context Protocol) is the underlying protocol that's frequently hinted at here without being named. It was introduced by Anthropic in late 2024, originally to unify the interface between large language models and external tools and data sources, so the model doesn't need custom integration code for every service. In MCP, a tool self-describes to the model via a JSON schema: name, description, parameter definitions, and optional output schema and annotations. What the model receives at inference time is exactly this self-description, not your repo or your website. Understanding this is key—under MCP, a tool description is not human-facing documentation but a runtime machine-readable contract, and any missing information translates directly into randomness at sampling time.

The two most commonly skipped rows

Negative boundaries. A trigger condition without boundaries is an invitation for the model to over-call. Saying what the tool does not apply to takes one sentence but eliminates an entire class of misuse.

Retry rules. If a call can time out, the description must say what to do after a timeout—otherwise the model's default behavior (try again) is exactly what you can least afford. Whether or not your tool is paid, the shape of the sentence is the same: after a call is truncated, what should the model do?

Idempotency is the underlying concept for understanding retry rules. An operation is idempotent if executing it once and executing it multiple times produces the same result—querying the weather, reading a file. Conversely, charging a card, sending an email, or writing a record is non-idempotent, and repeating it produces side effects. After a timeout, the model retries by default, and it cannot judge on its own whether the call already took effect, so that judgment must come from you in the description. The semantics of idempotentHint: true is precisely "retrying is safe"—mark it wrong and the client may auto-retry on that basis, amplifying a small glitch into duplicate charges or duplicate writes. This is why the article stresses that annotations must be filled in truthfully.

The 7 check questions before publishing a tool

1. Trigger — Does the first sentence say when to call it, and does it name a task rather than a feature?
2. Boundary — Does it say what it doesn't apply to, including the nearest similar task?
3. Input — Can each parameter be filled in correctly without reading any other documentation?
4. Return — Does the output schema name what's returned, including which fields are always present and which are conditional?
5. Latency and cost — Does the description say how long a call might take, and whether calling again has a cost?
6. Recovery — After a truncated or failed call, is there a clear path other than "call it again"?
7. Annotations — Are the hints you declared true? Marking idempotentHint: true on a call that charges or writes is a lie the client will take seriously.

This checklist has two properties worth keeping. First, it can be checked without any model involved: items 1–3 and 5–7 are essentially "does this sentence appear in the description." Second, it's testable on failure: each question corresponds to a reproducible shape of erroneous call, so description changes can be regression-tested like any other contract.

Why publish descriptions rather than relying on prompting tricks

Take remote MCP servers as an example: an endpoint that answers a single question—give it two defensible options, and it returns which one it prefers, how large it judges the gap to be, and why—its full contract lives where the model reads it: the tool description, the parameter descriptions, and the output schema. The accuracy range, sample size, and methodology are published separately, because a model's reports about itself are worthless without checks from outside the model.

A description that answers all seven questions above makes a tool callable. A description that answers none of them reduces it to a coin flip with a schema.

MCP remote servers refer to implementations where the tool logic runs outside your own process and is called by the model over the network. Unlike local tools, remote calls add the real-world constraints of network latency, timeouts, partial failures, and billing, so information in the description about latency, cost, and recovery paths is even more essential. The example the article gives—an endpoint that only answers "which of two options do you prefer, how large is the gap, and why"—is valuable precisely because its correctness depends on an output contract that can be checked externally, not on the model's self-description of its own judgment. Publishing the range, sample size, and methodology separately is exactly so the model's answer has evidence outside the model to be checked against, avoiding the loop of "the model verifying itself."

One-line Summary

When a model calls a tool it sees only the name, description, and schema—the description is protocol, and must spell out triggers, boundaries, cost, and retry behavior.

Paragraph Summary

The article points out that when a model decides whether to call a tool, its context contains only the name, description, and parameter schema—READMEs and docs are not there—so a tool description is essentially a runtime protocol. The most expensive failures aren't crashes but silent failures: the model never calls, calls wrongly, or calls repeatedly, none of which throw an exception yet produce plausible but wrong answers. The fix point isn't in the code but in the fields the model can see. The author goes field by field explaining what name, description, parameter descriptions, annotations, and output schema should each answer, and especially stresses the two most commonly skipped rows—negative boundaries and retry rules. Finally, 7 check questions before publishing, which can be verified independently of the model, and each failure is reproducible and regression-testable.