What an Agent Should Know Before It Answers a Question About Your Study

The question that exposes an ungoverned study is a boring one. "Is OS_MONTHS a number here, and what is it measured from?"

Give an AI agent the raw data_clinical_sample.txt and it will answer. It will infer that the second # row is descriptions and not display names. It will read NUMBER and reach for integer. It will not know that the PATIENT_ID column in this file is the study's join back to the patient instrument, because nothing in a flat file says so. It will not know that attribute IDs must be UPPER_CASE for the portal to accept the study. Every one of those inferences is reasonable. Any of them can be wrong. And they will all arrive in the same confident register.

The failure is not that the model is weak. It is that we handed it a file when we could have handed it a model.

Consultation instead of inference

Once a study is governed, its schema is not something an agent parses. It is something an agent queries.

CoreModels exposes an OAuth-protected MCP endpoint — for example https://coremodels.example.com/mcp. An agent connects once, completes the OAuth flow, and from then on consults the governed model directly. The tools that matter for a cBioPortal study are read-only and run at Viewer role, which is exactly the right safety property: an agent can inspect and audit a study without holding any permission to change it.

get_vendor_integration_status is the natural first call. Given a graphProjectId and vendor: "cbioportal", it returns the project's last-import state — when the study was imported, the recorded state facts, the fingerprint and counts, and how many governed datasets the vendor identities resolve to. Called without a vendor, it lists every registered connector with its capabilities and expected artifacts. An agent orienting itself in an unfamiliar project starts here and learns what is actually governed rather than assuming what might be.

Auditing without touching anything

The tool that most changes how an agent behaves is audit_vendor_project. It takes a graphProjectId, vendor: "cbioportal", and the clinical staging files — inline under artifacts, or, when a payload is too large to inline, as artifactUrls the server fetches for you. Those fetches are SSRF-guarded: https only, no redirects, non-public addresses refused, response size capped.

What comes back is the same structured report a CI gate reads: coverage of what is and is not governed, drift in fields and types and allowed values, the cBioPortal conformance rules, the counts, and a Markdown report written for humans. It writes nothing.

That read-only guarantee is what makes it safe to hand to an agent. You can ask an agent whether a proposed study update drifts from the governed model, and the worst outcome is that it tells you the truth. And because errorCount > 0 is the same fail signal the build uses, an agent's assessment and a pipeline's gate agree by construction rather than by coincidence.

The findings themselves are what make agent reasoning checkable. attribute-id-not-upper on a named attribute. field-type-drift on another, with the governed type and the artifact type both stated. attribute-no-description as an aggregate per instrument with the offending attributes listed. An agent working from those is quoting evidence with stable codes and named subjects, not narrating an impression of a file. "This attribute will fail portal validation because its ID is not UPPER_CASE" is a claim you can go check.

Drafting from the model rather than from memory

An agent can also call generate_vendor_artifacts with vendor: "cbioportal" to produce an upload-ready staging-file header scaffold from the governed model: the four # rows and UPPER_CASE attribute IDs, derived from governed definitions rather than typed from recollection of what last study's file looked like. Pass typeNames to scope it to specific instruments.

This is the right division of labour. The agent drafts a conformant scaffold from the authoritative model; a human reviews and uploads it. Generation is read-only and produces an artifact. It pushes nothing to a portal, because CoreModels holds no portal credentials.

The verbs that do change the graph are deliberately not on the public endpoint. import_vendor_project requires Admin role and lives on the admin MCP endpoint only. An agent grounded on the public surface cannot mutate the governed model no matter how it is prompted — the boundary is a role check, not the agent's good behavior.

The semantics a flat file cannot carry

The deeper win is not the tooling, it is what the tooling can now say.

A governed cBioPortal study hands an agent the facts the TSV only implies. That PATIENT_ID and SAMPLE_ID are unique, not-null identities. That the sample file's PATIENT_ID is a reference to the patient instrument, so the study's central join is something an agent can traverse rather than guess at from a column name. That the description row became the element's description and the display name and priority were preserved as metadata, so an agent asking what an attribute means reads what a curator wrote rather than paraphrasing the identifier.

And critically: that the NUMBER datatype was mapped to a numeric kind covering integers and decimals alike, with the approximation recorded as lossiness. That record is the difference between an agent that knows the boundary of its own knowledge and one that manufactures certainty. An agent that can read "this was approximated, here is how" can hedge accurately — which is a far more useful behavior than confidence.

When a governed attribute has also been bound to an ontology term — an EFO, MONDO, or HP IRI chosen by a human after an advisory suggestion — the agent inherits that grounding too, and can name the concept by an identifier other systems recognize instead of by a local string.

The shift, stated plainly

An agent pointed at an ungoverned study infers structure, states guesses as facts, and cannot show its work. An agent pointed at a governed one consults a model, quotes coded findings, traverses a declared reference, reads honest lossiness, and stops at a permission boundary it cannot argue past.

Same model, same prompt. The difference is entirely in what we gave it to stand on.

The cBioPortal quickstart in the CoreModels integration docs lists the MCP tools and their arguments for a study if you want to point an agent at one.