The Agent Cannot Tell Which Column Is the Key

Give a capable AI assistant two REDCap exports and ask it to join them. Watch what it has to do.

It has to decide which column identifies a participant. It will probably pick the one named record_id, and it will probably be right, because that is the default — but the record id is whatever the project's first variable is called, and projects rename it. Nothing in the export says "this is the key." The assistant infers it from the name, the cardinality, and the fact that it worked. Three heuristics stacked on top of each other, producing a join that will be quietly wrong in the one project that named it something else.

That is the shape of the problem. Not a lack of capability — a lack of ground truth.

What an export withholds

REDCap exports are built for people who have the codebook open in the next window. For an agent working from data alone, four things are missing at once.

The key is undeclared. As above: a convention, not a statement.

Categorical answers are bare codes. A sex column of 1s and 2s carries no labels; those live in the project's choice list. An agent that assumes the ordering is guessing, and being right most of the time is precisely what makes the exception dangerous.

Missingness has structure that the data does not show. Branching logic means a field can be empty because the participant skipped it or because the form never asked. Those are different facts about the world and identical cells in a CSV.

Nothing marks PHI. Whether a column carries an identifier is invisible in the data itself, which means an agent asked to "summarize the dataset" may read a medical record number without ever knowing it did.

In most domains an inferred column meaning produces a wrong chart. In clinical research it produces a wrong finding, or a privacy incident.

What the governed model states outright

Importing the data dictionary into CoreModels turns all four of those inferences into lookups.

The record id stops being a convention: the first variable in the dictionary becomes the instrument's identity, declared unique and not-null. Choice lists become governed taxonomies where the labels carry the meaning and the numeric codes are preserved alongside them as REDCap metadata, so a code resolves to a label by lookup rather than by hunch. Validation types become real data types — integer stays integral, number and calc are doubles, yesno and truefalse are booleans rather than strings that happen to contain 1, and the date validations are DateTime. Required Field? = y becomes a not-null check. Branching logic rides on each field's metadata, so the structure of missingness is inspectable instead of assumed. And every field marked in the Identifier? column is inventoried rather than buried in row 412.

For an agent, the shift is categorical: from reconstructing what a project probably means to asking what it actually means, with something to cite.

Consultation over MCP

The asking happens over the Model Context Protocol. CoreModels serves an MCP endpoint at /mcp, OAuth-protected, carrying strictly read-only tools. A grounded agent's first moves on a REDCap question look like this: list_projects to find the governed project, get_project_summary for its types, elements, and taxonomies, get_vendor_integration_status with vendor set to redcap for what was imported and when — the state, the fingerprint, the counts, the number of governed datasets — and search_nodes to pull the specific instrument or variable in question.

When the task needs a schema rather than a browse, the same endpoint exports the governed model in the dialect the work requires: JSON Schema, LinkML, ShEx, Avro, SQL, JSON-LD. And validate_json checks a document against the project's stored schema, so an agent proposing a payload can verify it instead of asserting it.

The habit worth instilling is simply: consult before you compute.

Verification, not vibes

Reading is half of it. The audit is an MCP tool too — audit_vendor_project, taking graphProjectId, vendor, and artifacts with the dictionary CSV inline, or artifactUrls when the payload is too large to inline. It returns the same thing the build gate gets: counts, findings with stable codes and named subjects, and a markdown report.

So when someone asks an agent "is this site's dictionary still aligned with the study?", the agent does not have to reason impressionistically across two CSVs and hope. It runs the same deterministic audit engine every human on the project runs, and reports coverage, drift, and conformance findings by code. Because the tool is read-only by construction, delegating that check risks nothing — the worst outcome of an agent auditing too often is a slightly warmer server.

The boundary the agent should respect

One finding is aimed directly at this new class of consumer. The phi-fields conformance finding names the identifier fields per instrument and says, in the message itself, to inventory them before any export or agent access. That is not decoration. An agent can and should be instructed to consult the inventory first and route around those fields entirely.

Grounding is not only about being right. It is also about knowing where not to look, and a governed model is the only place that boundary can be stated in a form an agent can read.

Where agents stop

Everything above lives on the read-only endpoint. Writing is a different world: importing an estate requires an administrator role and the separate admin endpoint, and changing what a study means — adopting a drifted field, retiring a value from a taxonomy — stays a human act regardless of how the request arrives. Agents observe, verify, and propose. People decide meaning.

We think that division is not a temporary caution but the correct long-term shape. The value of an agent on a research project is that it can check ten dictionaries before lunch and cite its findings. The value of a governed model is that its answers were reviewed by someone accountable. Neither substitutes for the other, and the combination is strictly better than either alone.

Every team pointing an AI system at its research data is choosing between precise semantics and guessed structure, whether or not the choice is made out loud. Guessed structure is free and silently wrong. Precise semantics costs one import of a file you already have.

To connect an agent to a governed REDCap project, start with the REDCap quickstart in the CoreModels integration docs.