The Expensive Kind of Wrong: Agents, LinkML, and Guessed Semantics

The costly failure of an AI agent working on schemas is not the one that errors out. It is the output that is perfectly well-formed and quietly invented — valid YAML, sensible field names, a plausible type for every slot, and three or four decisions nobody made. It passes review because it looks like the work, and fails in production.

That failure has one root cause, and it is not the model's reasoning. It is that the agent was working from a fragment somebody pasted, with no way to know how old it was, which project it belonged to, or what it left out.

What gets guessed when there is nothing to consult

Ask an agent to extend a downstream contract "consistently with the model," give it a sample of records, and watch what it must invent:

• Ranges. A date arrives serialized as a string, so it becomes a string.
• Enum closure. Three values appeared in the sample, so the enum has three members — and the rare fourth, the one that shows up only in edge-case data, is gone.
• Optionality. Every field was populated in the sample, so everything looks required, or nothing does.
• Meaning. A field called sex gets mapped to whatever a field called sex usually means, rather than to the ontology term the working group chose.

Each is defensible from the evidence available — which is the problem: the agent cannot flag them as guesses.

Consultation replaces the paste

CoreModels exposes the governed model over MCP. The public endpoint is /mcp, protected by OAuth, and it serves read-only tools only — write tools live on a separate admin endpoint, with per-project Editor/Admin role checks enforced server-side, so on the public endpoint a write tool is not merely refused: it does not appear in the listing at all. Every tool carries an explicit read-only hint, so a client can tell before calling which operations change anything.

The discovery path is short. list_projects finds the project. get_project_summary returns the labels and ids of its types, elements, and taxonomies. search_nodes narrows to the part of the model the question is about. When the agent needs the model itself, export_linkml returns the governed project as a LinkML YAML schema string — optionally scoped to a space or to specific type node ids, so a question about two classes need not pull in the whole estate.

The agent stops working from an artifact of unknown provenance and starts working from a named project it can cite.

Why LinkML is a good thing to hand an agent

Of the available projections, LinkML is unusually well-suited to being read by a model: it declares what other formats leave to inference.

Ranges are named, not implied. A slot ranging over another class is a reference to that class; a slot ranging over an enum is a reference to that enum. Nothing has to be worked out from a sample.

Enums are exhaustive by construction. permissible_values is the complete list, including the values the agent would never have seen. No sampling ceiling.

Optionality and cardinality are stated. required and multivalued are flags in the document, not frequencies in the data.

Meaning is a resolvable identifier. class_uri, slot_uri, and meaning bind classes, slots, and permissible values to ontology terms — the difference between "this field is probably about administrative sex" and a hard reference to a defined concept two systems can agree on without either guessing. And because the export computes its prefix block from the body, every CURIE the document uses is declared in that same document — expandable without a lookup.

It is also compact: a YAML model costs far fewer tokens than the equivalent JSON Schema, which matters when the useful move is handing over the whole model rather than a fragment.

Converting without inventing

When the task is genuinely a conversion — this LinkML model into Avro for a registry, a partner's SQL DDL into LinkML for review — transform_schema runs it statelessly through the mapping engine, across the same format keys the HTTP surface uses, with linkml available on both sides.

What comes back is the useful part: the produced schema, the executed plan, and the lossiness ledger. That ledger is the agent's uncertainty report, and it is not self-assessed. If the target could not hold a controlled list, a term hierarchy, or collection bounds, there is an entry naming the kind, the path, and the reason. An agent instructed to surface it can answer honestly: "here is the schema, and here are the four things it does not carry."

For instances rather than shapes, validate_json checks a document against the project's stored JSON Schema — read-only again.

Where the human stays in the loop

Grounding an agent is not delegating to one, and the boundary is drawn in the tool surface, not in a prompt.

Writes live on the admin endpoint and require Editor or Admin membership. Ontology suggestions are advisory by design: suggest_ontology_terms searches the public Ontology Lookup Service, returns ranked candidates with their IRIs, and states in its own response that suggestions are advisory and nothing was written. Binding a term is a separate, deliberate act — bind_ontology_term, Admin only, writing exactly one mapping value for the IRI you named, with unbind_ontology_term removing that one and nothing else.

The ai mapping kind follows the same principle one level down. A model may propose a mapping plan, but the proposal goes through the identical validation gate as an authored guide or an inferred plan, with at most one repair attempt — a rejected repair is a rejection. Any confidence score it carries is advisory; the gate does not read it. And because that path sends schema content to an external model API server-side, it requires Editor or Admin membership, not the Viewer access every authenticated user holds.

The workflow worth standardizing

For agents working on schemas the shape that holds up is: consult before answering, export the governed model rather than accept a paste, cite the project you read, convert through the engine instead of writing target syntax from memory, report the lossiness ledger in the answer rather than as a footnote, and suggest bindings rather than make them.

None of that asks the agent to be more cautious. It asks the schema surface to make the honest thing the easy thing — a design problem, not a prompting problem.

The MCP quickstart in the CoreModels documentation covers connecting a client and completing the OAuth flow.