Agents Need Schemas, Not Just Docs

The standard advice for getting an AI agent to work with your data is “point it at your documentation.” Confluence pages, README files, the data dictionary, the BI tool’s tooltips. The agent reads, the agent understands, the agent helps. This is the wrong instinct, and it’s the reason most data agents in 2026 are demo-grade rather than production-grade. The agent doesn’t need your docs. It needs your schemas, your metrics, your contracts – the structured artefacts that humans wrote the docs about.

Why docs aren’t enough

Documentation is what humans write to remind themselves of structure they understand intuitively. It’s fragmented, partial, often outdated, and pitched at the level of detail a human reader can fill in by intuition. The agent has no intuition. It needs the structure made explicit.

Take a typical Confluence page describing the customer data model. It mentions that customers joins to orders on customer_id. It probably mentions some quality caveats (“watch out for the legacy migrated rows”). It doesn’t mention the dozen other tables that look like they could be customer-related but aren’t. It doesn’t mention which fields are PII. It probably doesn’t mention the data freshness. It almost certainly doesn’t describe every metric defined off the table or who owns it.

The human reader fills these gaps. The agent can’t. So the agent reaches conclusions that look plausible and are wrong in ways the human reader would catch.

What “schemas” really means

When I say agents need schemas, I mean something broader than “the CREATE TABLE statement.” The fuller artefact looks more like:

Column-level metadata. Name, type, nullability, definition in business terms, valid value ranges, PII classification.
Join graph. Which tables join to which, on what keys, with what cardinality, with what caveats.
Quality assertions. What the data is supposed to satisfy, expressed as testable rules.
Freshness and SLA. When was this last refreshed; how often does it refresh; what’s the expected latency.
Metrics defined on top. The metric layer that says “revenue is the sum of these columns minus those columns, filtered to these conditions.”
Lineage. What feeds this table, what consumes it.
Ownership and contact. Who fixes it when it breaks.

This is the metadata an agent needs to reason about a dataset usefully. Most of it isn’t in documentation. It’s in scattered tools (dbt, the catalog, the BI tool, the warehouse) or in human heads. The work of making it agent-readable is the work of making it explicit, structured, and machine-accessible.

The metadata-as-tool-input pattern

The architecture that’s working in 2026 looks like this: the agent exposes tools for querying the catalog, the semantic layer, the lineage, the quality test results. The agent asks “what tables relate to customers,” gets a structured answer. Asks “what’s the definition of customer revenue,” gets a structured answer. Asks “when did this table last refresh,” gets a structured answer. Then it composes those answers into a query.

This is much better than dumping a Confluence page into the prompt. Each tool call returns structured data that the model handles reliably. The model can iterate – ask for more detail on a specific table, drill into a specific metric – rather than trying to comprehend a 50-page document in one pass.

It also makes the agent’s reasoning auditable. You can trace which tools it called, what it learned at each step, what query it generated. The path is inspectable.

The empirical test

A test I’ve been pushing on this: strip the data itself away and hand the metadata alone to an LLM. Ask it ten substantive business questions about the dataset. If it can’t answer 80% of them from metadata alone, the metadata isn’t agent-ready and an agent with access to the data won’t reliably do better. The data is what the agent will look at; the metadata is what the agent will use to decide how to look at it. The decision quality is bounded by the metadata.

Most enterprises fail this test on their first attempt. The metadata is incomplete, inconsistent, or written for humans rather than for systems. Fixing it is what the work of “preparing for agents” actually consists of. Not buying an agent platform; making the underlying metadata describe the data well enough that an agent can work.

The contracts angle

This is also where the data contracts and semantic models conversations converge. A well-specified data contract is agent-ready metadata. A semantic model is agent-ready metadata. The work people have been doing in those areas for analytics reasons turns out to be the same work needed for agents. The investment compounds.

The organisations that already have rigorous semantic models and contracts are agent-ready almost by accident. The ones that have neither are not, and pouring an agent on top doesn’t fix it. Building the metadata layer first is the unglamorous but necessary path.

The practical work

Audit your existing metadata. What’s captured, where, and how machine-readable is it.
Run the metadata-only test on a representative sample. See where the agent fails.
Fill the gaps in structured form, not as docs. Semantic models, contracts, catalog entries.
Expose the metadata via tool-callable APIs. Agents reason better with iterative tool calls than monolithic prompts.
Maintain it. Stale metadata is worse than absent metadata.

The data agent isn’t a feature you turn on. It’s the consequence of having the structured metadata to support it. The agent is mostly commodity; the metadata is the differentiator.

Next week – the semantic layer renaissance, and why dbt’s metrics and OSI are the same conversation viewed from different angles.