The Wrong Schema an Agent Writes Looks Exactly Like the Right One

Here is the failure mode that costs teams real time. You ask an assistant to draft a JSON Schema for the customer object it is about to integrate against, and it produces something clean: sensible property names, a tidy required array, an enum on the status field, format: "date-time" where a timestamp belongs. It looks like something your team would have written. It goes into a pull request and gets approved.

It says customerId; your model says customer_key. Its status list contains cancelled; your taxonomy says closed. It marked email as required; your model does not. Every one of those is a plausible guess, and plausible guesses are the hardest kind of wrong to catch, because nothing about the artifact signals uncertainty.

Fluency is not knowledge

JSON Schema is a format language models handle with striking fluency. It is everywhere in their training data, its structure is regular, and the shape of a correct answer is easy to produce. That fluency is genuinely useful — and it is exactly why JSON Schema is a high-risk artifact for an agent to author unaided. The model knows the notation perfectly and knows your content not at all, and the output gives you no way to tell those two things apart.

The fix is not a more careful model or a longer prompt. It is making the truth cheaper to fetch than to invent.

Grounding is a tool call, not a memory

A CoreModels deployment serves an MCP endpoint — https://coremodels.example.com/mcp, secured with OAuth — carrying read-only tools that any spec-compliant client can discover and use. The grounding loop is short enough that an agent will actually run it:

list_projects to find the workspace. get_project_summary for the labels and identifiers of the types, elements, and taxonomies it holds. get_mixins_and_relation_groups for the project's schema definitions, and search_nodes when the agent needs to find one specific thing rather than read everything.

Then, when it wants the governed structure in the notation it reads best: fetch_json_schema_import_profiles lists the project's profiles, and export_jsonschema returns the project as a JSON Schema string — optionally scoped to a space, a profile, and a root node. What comes back is not an approximation of your model. It is your model: the real property names, the real required list, the real enum values, references between types, inheritance expressed in standard allOf form.

That last part matters more than it looks. Handing an agent the governed model as JSON Schema is a high-bandwidth way to move precise structure into its context, in a notation it will not misparse. You are not fighting its fluency. You are aiming it at something true.

Precise semantics beat inferred structure

Structure alone still leaves meaning to guesswork, and that is where a governed model earns its keep.

A taxonomy is not a comment listing suggested values; it is the set of terms, with identity. An agent that reads it does not have to decide whether cancelled is close enough to closed. A required flag is a fact about the model, not an inference from three sample payloads. And the x-maps-to annotation attaches a standard and a term URI to a Type or an Element, which changes the question an agent can answer. Instead of "do these two fields have similar names?" it can ask "do these two fields bind to the same term?" — a question with an answer rather than a confidence score.

Because that annotation lives in the model rather than in one format, it survives into a LinkML export, an ontology export, a DDL comment. An agent grounded once stays grounded across formats.

Conversion that comes with a receipt

Agents are frequently asked to convert: this JSON Schema into that DDL, this partner file into our shape. Done by generation, the result is a confident artifact with unknown fidelity.

The transform_schema tool does it through the same engine our API uses. The agent names a source format and a target format from the supported keys, picks a mapping strategy — inferred label and type matching against a target hint, explicit with an authored guide, or ai — and gets back three things: the produced schema, the executed plan as a replayable artifact, and the complete lossiness ledger.

The ledger is what makes an agent trustworthy in this workflow. Instead of "here is your Postgres DDL," it can report: here is your DDL, and here are the three things that did not survive — this enum could not be enforced as an inline constraint, this conditional combinator could not be modeled as structure, this type was approximated. Each entry carries a kind, a path, and a plain-language explanation. It turns the agent from an author into an analyst that shows its work.

What an agent is not allowed to do

Grounding is only half of trust; the other half is boundaries that do not depend on the agent behaving well.

The public MCP endpoint serves read-only tools only. Write tools live on a separate admin endpoint and are role-checked per project, and the role check is the enforced boundary regardless of which endpoint a token came from. Importing a JSON Schema into a space requires Admin. The AI mapping strategy requires Editor or Admin membership and a server-configured key, and its plan goes through the identical validation gate as a hand-authored one — a proposal from a model earns no shortcut. Tools that reach outside the deployment, such as fetching a schema from a URL, declare themselves as open-world in their annotations, so a client can see it in the tool listing before anything is called.

There is a pleasing symmetry in the tool contracts themselves: they are JSON Schema documents. Arguments are typed, identifiers carry patterns, and on the transform tool additionalProperties is closed — so an invented argument is rejected rather than quietly ignored. The same discipline runs through the engine: an unknown key in a mapping guide is rejected with a path-carrying error, because a silently dropped typo executes a plan nobody intended.

Asking beats inventing

An agent that guesses your schema is not a bad agent. It is an ungrounded one, doing the only thing available to it. Give it a consultation channel and the guessing stops — not because the model became humble, but because asking became easier than inventing, and the answer it gets back is the same one your warehouse, your registry, and your partner contract were generated from.

To connect a client to the endpoint and run the grounding loop yourself, start with the MCP quickstart in the CoreModels docs.