ADR 0270 — A served tool schema is written in 2020-12 keywords

Invariants: I13. Amends ADR 0185.

Context

The tool presentation is built in draft-07, the vocabulary the AI SDK converts Zod schemas in, so an agent tool and its presentation describe a tuple the same way. ADR 0185 made the MCP document match the 2020-12 stamp the SDK puts on it, but only for reusable subschemas (definitions → $defs). A tuple stayed in draft-07 form: items: [a, b] with the rest in additionalItems.

In 2020-12 an items list is not a schema. A client that validates each tool schema before offering the tool refuses it, and Claude’s MCP loader does exactly that:

“lights_set” (MCP server “base”): “schema/properties/rgb/items must be object,boolean”

A consuming project lost six tools with z.tuple inputs (an RGB triple, a point) this way. The server logged nothing: the tool was registered and served, only never offered to the model.

Decision

The MCP document is written in 2020-12 keywords, not only stamped with them. presentationMetadata passes the presentation through one translation (withDraft2020Keywords, src/json-schema/dialect.ts): the top-level definitions moves to $defs with its pointers, and at every schema position a tuple’s items list becomes prefixItems with additionalItems becoming items. The walk follows schema keywords only, so a default, an example or a property that happens to be called items is left as written.

The stitchkit MCP client applies the same translation to a discovered document that does not declare draft-07, so a server published before this change is still read with its tuples’ meaning.

The agent presentation stays draft-07: it is handed to the AI SDK, whose own conversion of the same Zod schema is draft-07.

Consequences

A tuple-typed tool is offered by Claude’s MCP client. Arity, order and the rest element are enforced as before. tests/mcp-tuple-schema-dialect.test.ts validates the served document with a 2020-12 meta-schema validator, keeps a control showing the refusal Claude reports for the untranslated document, and walks the document to check that no items list remains. The served bytes of every tuple-typed MCP tool change; no other tool’s document does.