Tool Descriptions Are the Contract
This series started with a claim: MCP and REST are two doors into the same kitchen. Three posts later, the comments have pushed the argument down to its foundation. One reader on dev.to said the useful test is whether both doors preserve the same auth, error, and idempotency behavior. Another warned about granularity drift and asked how anyone validates tool descriptions. Both are pointing at the…
Prose in MCP servers is crucial, as it determines which tool the agent selects, how it calls the tool correctly, and how it recovers from errors. The description appears three times in the sample repo: in the restaurant backend, in C# attributes for the Functions MCP door, and in Bicep for the APIM REST door. These descriptions are not identical, even though they should be consistent.
As the number of tools, teams, and changes grow, this inconsistency becomes more pronounced, leading to a drift in the contract. The description is essentially the API contract now, and it must be treated as such. The measurement post provides insights into the cost of descriptions - a realistic one runs about 111 tokens, while a verbose one reaches 208 tokens per tool.
The budget question revolves around what each sentence buys. A good description should state what the tool does, when to call it, and where values come from. Provenance is particularly valuable, as it specifies where values originate, preventing agents from making assumptions and hallucinating identifiers. The measurement post's verbose tier mainly adds ceremony that the model could infer anyway, so focus on disambiguation and provenance.
The parity test checks if the doors agree on the decision, not if they use the same language. The MCP door returns instructions instead of machine-shaped errors, reflecting the different error handling approaches. However, the error messages serve a dual purpose - indicating the source of the problem and providing recovery guidance.
These messages act as constants, helping identify specific misunderstandings. By instrumenting the errors returned by these messages, you can create a quality dashboard that tracks the health of your descriptions. Validating the contract doesn't require advanced LLM tools; start by treating descriptions as artifacts that can be checked through CI.
Lint the descriptions to ensure identifiers have provenance, include "when-to-call" clauses, and monitor token usage through the measurement post. Drift between descriptions can be tracked using machine-readable Bicep descriptions and code attributes, allowing for automated tests to detect inconsistencies.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
