# Metadata is the easy part of a data context layer

By Patrick Kemp · Oct 27, 2026 · https://www.getzep.com/blog/metadata-easy-part-data-context-layer/ · Tags: Context engineering, Context graphs

Data agents rarely fail at SQL. They fail at choosing the right table, metric or join key. We read 15 engineering write-ups to see how teams fix it.

**Key takeaways**

- **Data agents now fail on context more than on SQL.** In a 2026 benchmark study, agents on the strongest model failed more often at finding the right data than at writing the query.
- **A data context layer is the information that an agent retrieves before it answers.** We read 15 write-ups from engineering teams that have built one. Most of the teams use a common design, and all 15 start with table metadata.
- **Most business context lives outside table metadata.** Decisions, exceptions and account terms are usually found in internal documents and chat threads. 13 of the 15 teams depend on people to write or approve this context manually.
- **A recent fact is not always a valid fact.** A message from today can describe a rule for last year's data. 10 of the 15 teams check for stale data or context, but none of the write-ups describes a record of when a business fact applied.
- **The next step is a store of business facts with dates and sources.** An ingestion pipeline reads documents, chat threads and contracts to extract facts. Each fact keeps the period when it was true and the source it came from. Agents read from this [temporal context graph](https://www.getzep.com/platform/context-lake/) during task execution.

---

An analyst asks a data agent for revenue by account for the first quarter of 2025. The agent finds the right tables. The query runs and returns numbers that look correct, but the metrics are wrong. A data migration in September 2025 changed the key that joins orders to accounts, and the agent didn't know. Its notes give only the new key, and orders from the first quarter still use the old one.

This type of error becomes more important as models improve. A September 2026 research paper from researchers at UC Berkeley and Stanford University tested data agents on benchmarks across model generations. Errors from tool use and code execution decreased with each generation. With the strongest model, more than 60% of the remaining failures came from a wrong reading of the data environment ([Patel et al.](https://arxiv.org/abs/2609.03141)). In these failures, the agent misread the question or chose the wrong data to query, such as the wrong table or join key.

To see how teams prevent these errors, we read 15 engineering write-ups published this year by teams that built internal data agents. The write-ups come from teams at OpenAI, Anthropic, LinkedIn, Spotify, DoorDash, GitHub and Cloudflare. The full list is at the end of this post. Although implementation details differ, the system designs all share a similar shape and agent context problem. They answer the first question well: which table and which join. They have no common answer to the second: which business facts apply, and when.

## How teams build a data context layer

An agent can write SQL, but in a warehouse with thousands of tables, it doesn't always know which table, join key or filter to use. The data context layer gives the agent this information before it writes the query. Most teams construct the layer from three parts:

1. **Table metadata.** This is written information about each table: what it holds, what each column means, how it joins to other tables and which filters analysts usually apply. Teams derive it from schemas, query history, sample rows and the code that builds each table. Several teams use a language model to write a first description of each table from these inputs.
2. **Notes that people write.** Data owners add definitions, exceptions and known data-quality issues that the inputs above do not show. Many teams keep these notes as text files in Git, and the table owner approves each change in a pull request. Some teams keep these notes in a store separate from the table descriptions, so that a pipeline that regenerates the descriptions cannot overwrite a correction that a person made.
3. **Retrieval.** The agent does not load all of this context into its prompt. It calls a tool, often through MCP, and gets the context for the tables in the question.

![Two lanes of context, machine-written table descriptions and human-written notes, reach a data agent through one retrieval tool.](https://www.getzep.com/blog/metadata-easy-part-data-context-layer/fig-01-common-design.png)

Machine-written and human-written context stay separate, so a regeneration cannot overwrite a correction.

This design prevents one type of failure: use of the wrong table, field or join. It does not remove the need for people. In the write-ups that we read, a person owns each business definition, and a description that a model wrote is only a starting point for that owner.

## Most business context lives outside table metadata

The context that an agent needs to answer business questions is not always found in table metadata. Suppose an analyst asks why enterprise churn changed last quarter. Table metadata tells the agent which subscription table to use and how to join it to accounts. The answer to "why" is in three other places:

- A pricing decision from a leadership meeting in the second month of the quarter.
- A chat thread in which a data owner explained that one account's renewal is recorded under a new parent company.
- The contract for a large account, with a termination clause that started that quarter.

![A churn question points to table metadata and to three business sources: a meeting, a chat thread and a contract.](https://www.getzep.com/blog/metadata-easy-part-data-context-layer/fig-02-answer-outside-metadata.png)

Table metadata finds the tables, and the answer is in three other sources.

The teams fill this gap in two ways, and 7 of them use both. In 13 of the 15, people write or approve the business context manually. They copy guidance from a thread into a note and open a pull request, or they write domain documents for the agent. In 8 of the 15, an automatic path reads or generates context from other sources, such as query history, chat or issue trackers.

Both methods have a cost. A written note depends on a person who has time to write it, and until then the knowledge stays in the thread. Search over raw chat finds the text, but the agent must then decide which of several messages is still correct.

## Facts that go stale

Stale context has a large cost. One team saw its agent's accuracy on its evaluation set fall from about 95% to about 65% in the month after launch. The team's documents described a data model that changed every day. The team fixed the problem by keeping each document in the same repository as the model it describes. Now about 90% of its data-model pull requests also update a document ([Anthropic](https://claude.com/blog/how-anthropic-enables-self-service-data-analytics-with-claude)). This fix works because the document and the model change in the same pull request. A business fact that changes in a meeting or a contract has no pull request.

Most teams take stale context seriously. 10 of the 15 write-ups describe a way to catch information that goes out of date. Some teams regenerate table descriptions on a schedule, some test each change, and others query a table live before the agent trusts its description. All of these controls check how recent a record is. For table metadata and for the data itself, the most recent version is usually the correct one.

Business facts need a second check: whether a fact is valid for the period in the question. A recent record is not always a valid fact. A rule for last year's data can arrive in today's message, and a contract term signed two years ago can still be in force. A check on recency alone would apply the new rule to every period and mark the old contract term as stale. Some teams version their governed metric definitions, and some warehouses can query a table as it was at a past time. Both help, but neither covers a fact that came from a chat thread or a contract.

Researchers see the same open problem. The paper from the start of this post calls it semantic consistency. The stored context becomes wrong whenever a schema changes or a definition is rewritten. User corrections have the same effect. A change to one item can also make other items wrong, with no explicit link between them. The authors suggest that context layers will need mechanisms like multi-version data management, and they list the problem as an open research question.

## What a complete data context layer includes

A complete data context layer has five parts:

1. Table metadata: what each table holds, how tables join and which filters apply.
2. Business source ingestion: documents, chat threads, contracts and other business records, loaded as they change.
3. Dated facts: each fact keeps the dates it applied and its source, so that an agent can answer for a specific period.
4. Access controls: rules that decide which context each agent can retrieve.
5. One retrieval interface: a single way for the agent to get context, for example MCP.

The systems in the write-ups already have parts 1, 4 and 5, and many have some of part 2. The next step is parts 2 and 3, which work best as one system. A [note in a file](https://www.getzep.com/blog/markdown-is-not-agent-memory/) is a sentence that a person must write. A temporal context graph stores business facts as records instead. Each record connects two things, such as an account and a contract term, and keeps the period when the fact was true and its source.

This structure fixes both problems above. First, people no longer copy threads into notes. An ingestion pipeline reads each new document or chat thread, extracts the facts and adds them to the graph with a [link to their source](https://www.getzep.com/blog/how-zep-tracks-provenance-in-agent-memory/). People still own the definitions. They review and correct the facts, but they do not write each one.

Second, the graph keeps time. A new fact that contradicts an old one closes the old fact's period instead of overwriting it. The join key from the start of this post becomes two facts: the old key, valid until the migration, and the new key, valid after it.

![A Q1 2025 revenue question goes to table metadata and to a temporal context graph, which returns the old join key, valid until September 2025.](https://www.getzep.com/blog/metadata-easy-part-data-context-layer/fig-03-metadata-and-context-graph.png)

The graph keeps both join keys with their dates, so a question about Q1 2025 gets the old key.

The agent can ask what was true for an account last quarter and get the correct answer for that period. The graph does not replace table metadata. The agent reads both through the same retrieval interface.

| Question | Table metadata | Temporal context graph |
|---|---|---|
| Which table has active subscriptions? | **Answers it** | Not its job |
| Which join key is correct for 2025 orders? | Undated note | **Dated fact, with source** |
| Why did enterprise churn change? | Tables only | **Decisions and exceptions** |
| What did we know on a past date? | Git history | **Point-in-time query** |

Table metadata and a temporal context graph answer different questions about the same data.

The systems in the write-ups answer the first question well: which table and which join. The second question, which business fact applied and when, needs a store that keeps each fact with its dates and its source. That temporal store of business information is the next part of the data context layer.

## FAQ

### What is a data context layer?

A data context layer is the information that a data agent retrieves before it answers a question about warehouse data. It usually includes table and join descriptions, definitions and exceptions that data owners write, and the tools that the agent calls to get them. A more complete layer also includes business facts from documents, chat threads and contracts, with the dates when each fact applied.

### Is table metadata enough context for a data agent?

Table metadata tells a data agent which table and which join to use. That is enough for many questions about what the data contains. Questions about why a number changed, or which rule applied in a past period, depend on decisions and contract terms. Those facts are usually outside table metadata, in documents and chat threads.

### How do you keep agent context from going stale?

Table metadata stays current through scheduled regeneration, tests and owner review. Business facts also need the dates when each fact applied and the source it came from. With those dates, a new fact that contradicts an old one closes the old fact's period instead of deleting it. The agent can then answer for the current period or for any past period.

### What is the difference between recent and valid context?

Recent context was loaded or edited a short time ago. Valid context applies to the period in the question. A new message can describe a rule for old data, and an old contract term can still be in force. An agent that ranks context only by recency can apply a current rule to a past period.

### Does a temporal context graph replace table metadata?

No. Table metadata describes what each table holds and how tables join. A temporal context graph holds the business facts around the data, such as decisions and account terms, with the dates they applied and their sources. A data agent can use both through one retrieval interface such as MCP.

## Sources

This post draws on 15 public engineering write-ups about internal data agents. The counts in this post are our reading of what each write-up describes. A design element that a write-up does not mention can still exist in the system.

Research: Liana Patel, Siddharth Jha, Negar Arabzadeh, Carlos Guestrin, Ion Stoica and Matei Zaharia, ["What Happens When the Model Eats the Stack? Rethinking the Research Agenda for Data Agents to Withstand the Bitter Lesson"](https://arxiv.org/abs/2609.03141), arXiv preprint, 2026-09-02. Failure clusters: section 2 and Table 1. Semantic consistency: section 3.1.

Engineering write-ups:

- LinkedIn, [Inside LinkedIn's data context layer](https://www.linkedin.com/blog/engineering/infrastructure/inside-linkedins-data-context-layer-curating-trustworthy-context-for-humans-and-agents) (2026-10-09)
- Clay, [Building monty, Clay's self-serve analytics agent](https://www.clay.com/blog/building-everyones-personal-data-scientist) (2026-09-30)
- PKSHA, [Building an AI-native data analysis platform](https://zenn.dev/pksha/articles/5a1dc6470019d6) (in Japanese, 2026-09-17)
- DoorDash, [Inside Vera, DoorDash's data agent](https://careersatdoordash.com/blog/inside-vera-doordashs-data-agent/) (2026-09-16)
- Snap, [DS Agent: Snap's AI data scientist](https://eng.snap.com/ds_agent) (2026-09-10)
- Snowflake, [Building an internal context layer for AI agents](https://www.snowflake.com/en/blog/snowflake-internal-context-layer-for-ai-agents/) (2026-08-17)
- Grab, [How AI is transforming analytics at Grab](https://engineering.grab.com/how-ai-is-transforming-analytics) (2026-08-01)
- Bitrise, [Data Mage: meet our AI data analyst that lives in Slack](https://bitrise.io/blog/post/data-mage-meet-our-ai-data-analyst-that-lives-in-slack) (2026-07-22)
- Augment Code, [An AI analyst that reads Linear, Slack and GitHub](https://www.augmentcode.com/blog/an-internal-ai-analyst-that-reads-linear-slack-and-github-and-answers-off-our-dbt-models) (2026-06-29)
- GitHub, [How we built an internal data analytics agent](https://github.blog/ai-and-ml/github-copilot/how-we-built-an-internal-data-analytics-agent/) (2026-06-19)
- Spotify, [Encoding your domain expert: the context layer behind Spotify's data assistant](https://engineering.atspotify.com/2026/6/encoding-your-domain-expert-the-context-layer-behind-spotifys-data-assistant) (2026-06-10)
- Anthropic, [How Anthropic enables self-service data analytics with Claude](https://claude.com/blog/how-anthropic-enables-self-service-data-analytics-with-claude) (2026-06-03)
- Cloudflare, [How we built Cloudflare's data platform and an AI agent on top of it](https://blog.cloudflare.com/our-unified-data-platform/) (2026-05-28)
- Pinterest, [Unified context-intent embeddings for scalable text-to-SQL](https://medium.com/pinterest-engineering/unified-context-intent-embeddings-for-scalable-text-to-sql-793635e60aac) (2026-03-06)
- OpenAI, [Inside OpenAI's in-house data agent](https://openai.com/index/inside-our-in-house-data-agent/) (2026-01-29)