The Fine Print Is Where Agents Fail

Every data contract has a headline and a fine print. The headline is the list of columns and their types; any competent reader gets that right. The fine print is the rest: that this primary key is explicitly required: false; that this column is classified restricted and has an encrypted counterpart; that the quality check on the amount column demands a null count of exactly zero at error severity.

The fine print is where the risk lives, and fine print is precisely what statistical reading skims.

That is the problem with pasting a contract into a chat window. A language model reading YAML as text will answer the headline questions well and the fine-print questions plausibly — and plausible is a failure mode, not a result, when the document is an agreement two teams negotiated. Ask that model for the matching DDL and the failure sharpens: it emits something that looks right, including the helpful, wrong decision to make that primary key NOT NULL.

So we built our ODCS support to be something agents call, not something they imitate.

A tool call instead of a reading comprehension exercise

CoreModels exposes its transform engine over the Model Context Protocol — the open standard that lets an assistant call real tools. An agent connects to https://coremodels.example.com/mcp, completes OAuth, and gets typed, self-describing tools. The public endpoint serves read-only tools, so an agent exploring on a user's behalf cannot mutate anything by accident.

The tool that matters for contracts is transform_schema. It takes a source format, the source schema text, and a target format, and it runs the same deterministic path our HTTP API runs: decode, produce a mapping plan, validate that plan through the universal gate, execute, encode. odcs is available on both sides of that call — a contract can be the source, and a contract can be the target. The call is stateless: the project identifier scopes authorization and nothing else, so an agent can offer conversions freely without writing to a governed model.

When our engine emits a contract, the required head, the valid kind, and the property logical types are constrained by the specification's own enums — enforced by code that is checked against the standard's published JSON schema, not estimated by a model that has read a lot of YAML. When our engine reads a contract, required: false on a primary key stays false, because a decoder does not get helpful.

And when the input is not a contract at all, the agent gets a refusal with a reason it can relay — wrong kind, or none of the standard's identifying marks, or a parser error with its message — rather than a confident model built out of a Kubernetes manifest.

The ledger is agent food

Every result carries the lossiness ledger: typed records with a kind, an exact path, and a plain-English explanation. It is the single most useful thing we hand an agent.

Without it, an assistant reporting on a conversion can only claim success or hedge vaguely — "some information may have been lost." With it, the agent can say precisely: the time-of-day column was approximated as a datetime and the original type was preserved; the quality checks are kept verbatim rather than modeled; the controlled vocabulary on this column could not be expressed as an enum and came out as a string. Three named facts, each with a path, each traceable back to a line in the user's document.

An agent that can enumerate what changed is an agent whose user can decide whether it matters.

The engine returns one more artifact worth noticing: the executed plan, in full, replayable. An agent can show not only the output but the operations that produced it — and that plan can be re-run later for the same output, which is how a one-off conversation becomes a pipeline step.

After import, stop reading YAML entirely

The bigger shift comes once a contract has been imported into a CoreModels project. At that point the agent should not be reading the contract at all.

The same MCP server offers read tools over the governed model: list the user's projects, summarize a project's types, elements, and taxonomies, inspect its mixins and relation groups, search nodes, validate a JSON document against the project's stored schema, and export the model as JSON Schema, Avro, SQL, LinkML, ShEx, JSON-LD, or OWL. "Which fields are required on the payments table?" becomes a query against structured facts rather than a re-reading of a nine-hundred-line document that may not even fit in context.

This is what grounding means in practice. Not a better prompt — a different source. The contract's content stops being text the model must interpret and becomes data it can look up. (Turning a governed project back into a contract document is an export on the HTTP API, where read access is enough; over MCP the contract path is document in, document out.)

Where we let a model be creative, and how it is fenced

Exactly one place in this pipeline lets a model propose rather than execute: mapping one schema onto another, via an AI-proposed mapping plan.

That proposal receives no privileges. It goes through the identical validation gate as a hand-authored plan, with at most one repair attempt — a rejected repair is a rejection. The confidence score the proposer reports about its own work is advisory only; nothing reads it as permission. The path requires elevated project membership and a server-configured key, and is flagged as an open-world operation because it sends schema content to an external model service.

Proposing is what models are genuinely excellent at: drafts, mappings, translations, explanations. Deciding is not the same act. Between every proposal and every consequence sits a deterministic gate, and in front of anything that changes a governed model sits a human holding the right role.

Why contracts need this most

Schema work is steadily moving toward agents — drafted in conversations, converted in pipelines, reviewed by bots in pull requests. The question is not whether assistants will touch your data contracts. It is whether they touch them through an engine that knows the specification or through a paraphrase that sounds like it does.

A contract is an obligation negotiated in specific words, and fluent restatement is the wrong service to provide for it. Give an agent a conformant engine to call, an honest ledger to read, and a governed model to query, and the precision survives the trip through the machine — every deviation named, pathed, and on the record.

To connect an assistant and try it, see the MCP quickstart in the CoreModels docs.