Context

Context is the short, author-written description you attach to a table, model, contract, or collection that explains what it represents in business terms. It's the single biggest lever you have on the quality of answers from Gaur's chat and MCP surfaces.

If you've worked with coding agents that read a project's AGENTS.md, CLAUDE.md, or SKILL.md file before they touch anything, context is the same idea: a small amount of prose that tells the agent what it's looking at and how to use it correctly. Schema alone is not enough; column names rarely disambiguate themselves.

This page is the author's guide: what to write and where to attach it. For how the system reads context (which sections get embedded, what's silently dropped), see Context for AI.

Why context matters

An AI surface seeing only schema can pick the wrong identifier, the wrong join, or the wrong metric, and still produce a confident answer that's quietly wrong. Schema tells it what columns exist. Context tells it what those columns mean.

A real example: olist's two customer ids

The popular Brazilian e-commerce dataset (olist) has two customer-ish identifier columns, on two different tables:

orders.customer_id joins to customers.customer_id, but customers.customer_id is not the customer's identity, it's the order's snapshot of them. customer_unique_id is the identity.

Without context, an LLM asked "how many customers placed orders last month" will almost certainly do:

SELECT COUNT(DISTINCT customer_id) FROM orders WHERE ...

That counts orders, not customers, because every order has its own customer_id. The answer comes back inflated, and nothing about the schema gave the agent a way to know better.

With context, the agent knows customer_unique_id is the identity column and counts distinct values of that instead. Same data, correct answer.

This pattern, two columns that look identifier-shaped where only one is actually the entity's identity, is everywhere in real datasets. Order vs. customer ids, account vs. subscription ids, asset vs. transaction ids. The primary key you declare on each table covers half of this; context covers the other half.

What good context looks like

Aim for short, dense prose. Two paragraphs is usually enough; pages of prose hurt more than they help, because the agent has to read all of it.

Cover, in roughly this order:

• What the dataset represents and the grain of its rows. "Each row is one order line item, at the moment of purchase." Not "this is a table about orders."
• Which columns carry identity. Especially when more than one column looks like an id, name the one that's actually the entity's identity, and what the others are for.
• Business meaning of important columns. "amount is gross, before refunds. Net revenue is in the payments table." Things a column name cannot tell you on its own.
• Important enums and their meanings. "status = 'delivered' includes partial deliveries; use 'completed' for the strict definition."
• Known gotchas and exclusions. "Rows before 2022-03 are missing region. Exclude them or treat null as 'unknown'."

Skip:

• Restating column names and types. The schema is already loaded; saying it again is noise.
• SQL examples and joins. The agent writes its own queries against contracts; example queries date quickly and bias it toward your specific examples.
• Generic analytics advice. "Group by month to see trends." The agent knows how to group by month.

Aim for the prose a new analyst would need on their first day with the dataset. That's almost exactly what an agent needs too.

Where to put context

You can attach context at four levels. Use the most specific one that fits.

Context composes. When an agent reaches a contract through a collection, it sees the collection's context, the contract's, and the context of every underlying table or model the contract reads.

A worked example

Here's how the olist example might be written as context on the orders table:

Each row is one order placed on the marketplace.

customer_id is a per-order snapshot of the customer; a single person who places three orders shows up with three different customer_id values. To count or filter by people, join to the customers table and use customer_unique_id, which is stable across orders.

order_status of delivered covers fully and partially delivered orders. Use order_delivered_customer_date (not order_purchase_timestamp) when the question is about delivery, not purchase.

Orders before 2017-01 are sparse and missing several columns; analyses of historical trends usually exclude them.

That's short, specific, and tells the agent the four things it would otherwise get wrong.

How context flows to the agent

When a question hits the chat or MCP endpoint, Gaur surfaces the context attached to every object the agent looks at, alongside the schema and the primary keys. You write context once, and every consumer that exposes the object benefits from it.

This is also why context is part of the builder workflow, not an integrator concern. The person who knows what the data means writes it down; every integration after that gets the benefit.

Treat it like documentation

Context drifts the same way any documentation drifts. When a column's meaning changes, when a known issue is fixed, when a new identifier column appears, update the context too. Stale context is worse than no context, because the agent will trust it.

Next