Give the Agent Something to Cite

An engineer types into an assistant: add a refund_reason field to the payments event and update the two consumers that need it.

Count what the agent must know to do that correctly. Which subject holds the payments value schema, and which is the key. Whether the new field can be required without breaking existing readers. Whether refund_reason should be free text or a controlled list, and if a list, which one — because a governed set of reasons probably already exists. And whether any of that was agreed, or merely typed once by an engineer who has since changed teams.

Now count how many of those facts are retrievable from the estate as it stands. Usually: the first one, partly.

Streaming is where agents guess worst

An agent exploring a REST API can at least read example responses. Point one at a Kafka topic and it sees base64. The schema lives in the registry, indexed by a naming convention the agent must know to look for, and what it finds is structure without semantics: field names, types, unions, enum symbols. Whether an amount is gross or net, whether two enum symbols are distinct states or historical synonyms, which record a customer identifier points at — none of that is in the bytes, and little is in the schema once doc strings have decayed.

So the agent does what any generator does with a vacuum: it fills it fluently. It infers meaning from field names, invents plausible enum semantics, and produces a consumer that is syntactically perfect and semantically hopeful. In a streaming system, hopeful code doesn't produce a wrong number in a nightly report — it processes events incorrectly at full message rate, immediately.

Our audit has a conformance finding for undocumented fields on value subjects, and its wording names the problem: those fields "carry no doc — consumers and agents are guessing their meaning." Consumers and agents — the pairing was deliberate, because both fail the same way for the same reason.

From guessed structure to citable fact

Importing a subjects export replaces the vacuum with a model an agent can consult. Each subject becomes a governed Type; each field an Element carrying its type and Avro's own optionality, so "can this be null?" is a recorded fact rather than an inference from a field name. Enum symbols become governed taxonomies an agent can enumerate and point at. Named-record references are resolved across subjects, turning "these field names look related" into "this Type refers to that Type."

The registry's version and schema id ride along as metadata, so an answer can say which registered schema a governed fact describes — a reviewer can check it rather than take it on faith.

The difference is categorical. A guess and a governed fact may produce the same answer on a good day; only one can be cited, verified, and corrected.

Consultation over speculation, through MCP

These facts are served where agents work. CoreModels exposes an MCP server: point an MCP-capable client at https://coremodels.example.com/mcp, complete the OAuth flow, and the governed model becomes tools instead of prose. An agent orients itself by listing projects and reading a project summary, then reads the same Types, Elements, taxonomies, and references a human would.

The integration verbs are tools too.

get_vendor_integration_status tells an agent which connectors are registered, what artifacts each expects, and — with a vendor key — the project's last-import state: when the estate was imported, its fingerprint, how many datasets are governed. That is the difference between an answer qualified by "as of the last import" and one that quietly pretends to be live.

audit_vendor_project lets the agent run the audit itself. Hand it a fresh subjects export inline, or a URL to fetch when the export is too large, and it returns coverage, drift, and conformance findings with stable machine-readable codes, plus counts and a markdown report. An agent branching on field-type-drift or enum-narrowed is reasoning about identified facts, not parsing English. URL fetches are constrained — https only, redirects disabled, non-public addresses refused — because an agent-supplied URL is untrusted input.

generate_vendor_artifacts produces registry-ready Avro record schemas from governed Types — a proposal for humans to review and register.

The boundary that makes it safe

That last word — proposal — is enforced rather than aspirational. The public MCP endpoint serves read-only tools at Viewer role; importing an estate is a separate tool requiring Admin membership, served only on the admin endpoint. An agent can look up, verify, and draft anything. Changing governed meaning still goes through a person holding the right role.

This is not a hedge against agents being unreliable — it is the same boundary we apply to humans and CI keys. Grounding without a write boundary just relocates the guessing problem into the write path, where it costs more.

Honest gaps beat fluent fiction

A governed model has one property underrated for machine consumers: it knows what it does not know, and publishes it.

Protobuf subjects are counted but not parsed here, and every audit repeats that as a coverage finding with the count. An agent asked about one can answer "this part of the estate is not governed here" instead of confabulating a structure. Approximations — arrays, maps, bare-primitive key subjects, JSON Schema parsed at depth one — arrive as declared lossiness records, machine-readable like everything else.

For an agent, an honest boundary is actionable: flag the gap, route the question to a human, or recommend extending coverage. A fluent fabrication is actionable for nobody until it fails.

The documentation finding closes the loop from the other end: every undocumented field it names is a place where an agent would have had to guess, which makes a routine audit a map of your estate's agent-readiness, subject by subject.

Where this settles

Not "agents reading documentation" — agents inside the loop, with citations.

An agent on a schema pull request runs the audit, reads the coded findings, and explains what would drift and which subjects are affected. An agent drafting a new event schema starts from governed Types and generates Avro that respects agreed meaning — then hands it to a human.

The prerequisite is always the same: precise semantics, held somewhere an agent can query, honestly bounded. That is the difference between an agent that sounds right about your streams and one that is right — and can show you why.

Connecting an agent — the MCP tools, their arguments, and the subjects export recipe — is covered in the CoreModels Confluent Schema Registry quickstart in our docs.