Conventions MCP

Agent-Facing Contract Conventions

An MCP tool or CLI capability is a user interface whose user is a language model. A schema can be type-sound, validated, and documented and still be undrivable: models copy examples, fill every property they see, retry with the same call, and cannot inspect bytes. Design for that behaviour and measure it.

Target Property

A capable model, given only what tools/list and the reference resources expose, completes the workflow on the first or second attempt, and every rejection it receives names the next call to make. The authoring eval, not code review, decides whether a contract change helped.

Measure Before Believing

1. An eval is the acceptance test. Every agent-facing workflow has an eval that drives the real tools with the real schemas and scores each step separately (authored, created, configured, filled, or the workflow's equivalents). Run it before and after a contract change and put both tables in the PR. A change that is "obviously better" without numbers is a hypothesis.
2. Keep the rejected call, in the eval only. The eval records the raw input of every call the schema rejected before the handler ran; a pass rate without the rejected payloads cannot say whether the model or the contract failed. Eval fixtures are synthetic, so the trace may hold them whole. Production telemetry for a rejected call records the tool name, the issue codes, and the issue paths, never the payload: tool arguments carry matter content and personal data.
3. Parse through the schema the handler uses. The eval, the tests, and the handler must validate the same object; a normalisation that lives only in one handler's pre-step is invisible to the eval and drifts.

Shape Tools For How Models Behave

4. One tool, one intent. Split create, configure, and update into separate tools rather than one tool whose meaning depends on which optional arguments are present. Cross-field "provide A or B, not both" checks are a sign the tool has more than one job.
5. Few optionals, one discriminator. Replace a set of mutually exclusive optional keys with one discriminated union (source: { type: "ai" | "lookup" | ... }). A model that fills every property cannot produce a contradictory union member; it can produce six contradictory optionals.
6. Best effort over all-or-nothing for collections. When a call carries a list of entries, validate each entry independently, apply the valid ones, and return the rest as per-entry issues[]. One bad property must not sink a call that carried seven good entries.
7. Echo the next call. Return, from the call that discovers state, the exact payload the next call accepts (a configure skeleton, canonical path spelling, allowed values). Copying beats inferring. Read-back must round-trip: the shape a describe tool returns is the shape the configure tool accepts, byte for byte, and a test pins that fixed point.
8. Idempotent and re-entrant. Models retry with the same call and resend everything they know. Accept the resend: upsert on a stable id, idempotency keys that cover every argument, durable receipts replayed without re-executing.
9. Keep artefacts out of the model. Bytes are the hardest step in any loop. Prefer references (a host file reference, an id of something already stored) over inline base64; when inline is the only path, bound it by the request frame, derive the limit from the shared constant, and state it in the description. Never let an error hint invite the model to shrink or rewrite a document.

Every Error Is A Next Step

10. Structured envelope, closed codes. Failures return { code, message, hint, issues[] } with codes from a closed set. hint names the corrective action, the tool to call, and where to go (a deep link when the fix is in the UI). "Disabled" without "enable it here" is a dead end.
11. Never leak the substrate. A malformed id is a validation issue at the boundary, never a database cast error reported as internal_error. Every id input is declared with the shared id schema; a registry-wide test enforces it.
12. Warn about what the model probably meant. Discovery and save return warnings[] with closed codes for the known traps (unprefixed loop item, unknown directive, split marker, and so on). A census test keeps the code list and the reference in step.
13. Read each value kind leniently, in one place. A model spells a value the way its training data did: null for an unset optional, 4 000 for a number, 1. 10. 2026 for a date, ano for a boolean, cs_CZ for a locale. Every kind the wire accepts gets ONE owner that auto-normalizes the spellings carrying a single meaning and returns ONE ask-for-a-fix shape (received, expected, hint) when a spelling carries two: 01/02/2026 and a bare 1,234 are asked about with both readings named, never guessed, because guessing wrong is a wrong date or a factor of a thousand on an instrument. Null and the placeholder encodings are that rule for "absent" and live in the tool factory; the value kinds live in packages/agent-input/: number (a page size clamps with a note), boolean, date (a range bound reads 2020 as its first or last day and 0001-01-01/9999-12-31 as no bound), uuid (the all-zero and example ids are placeholders), filter (" ", "all", "-" mean "not filtering"), vocabulary (a data-owned value such as a court, read through case, diacritics, abbreviations and English names), string list (a lone string is a one-item list; only constrained tokens split on commas), ELI, country, locale, enum. A repaired value returns a note ("Read X as Y") that reaches the caller beside the result. A placeholder in an optional property is absence on a read and an ask on a write, where an optional id can switch update into create. An optional filter read against a data-owned vocabulary (court) never empties a search: a value that names no stored value, or several, is dropped with a warning naming the stored ones. A filter with no such vocabulary yet reads only its placeholders, and an empty page under it carries no_hits_filtered naming the values that would have matched; do not advertise resolution a filter does not do. An opaque token the server issues extends "absent" one step: a client filling every declared property invents a first-call cursor (" ", "0", "start"), so cursorInput reads a value outside the class its encoders emit as no cursor, while a value inside that class still reaches the decoder and fails through invalidCursorResult, which names the restart; restarting a damaged or invented cursor at page one silently would repeat a page the caller already read. Kinds a property's name implies (limit, date_from, date_to) are bound by the factory, so a new tool inherits them. Cover each kind with a property test over its whole spelling class rather than the examples someone happened to write down, and add a guard (an ownership row, a census test) so a new call site cannot parse the kind itself. Never per-tool tolerance code, and never a second reader: two lenient readers of one kind are worse than one strict one, because they disagree.