Context for AI

Schema alone doesn't tell an LLM what your data means. The customer column on raw_orders looks just like the customer_unique_id column on raw_customers until somebody explains that the first is a per-ticket snapshot and the second is the actual person. Without that, an agent asked "how many customers ordered last month" will count tickets and quietly return the wrong answer.

Context is the prose layer that fixes this. Every table, model, contract, and collection in Gaur carries a context document that gets surfaced to chat and MCP. Better context, better answers.

For the author-facing guide to writing good context, see Context. This page is the system side: what's in a context document, what's auto-generated, what you should edit, and what gets silently dropped if you don't follow the structure.

A context document has two sections

Every generated context document, whether for a table, model, contract, or collection, has the same top-level shape:

## Object Info
[structural facts: identity, fields, types, primary keys, sample enums,
 connections to other objects]

## Business Context
[prose: business terms, rules, use cases]

The split is intentional. Object Info is what Gaur can derive from the schema, sample rows, and your declarations. Business Context is what only you can write: the meaning behind the columns, the rules a query should respect, the kinds of analyses the dataset supports.

Both sections are embedded and made available to chat and MCP. Together they let an agent reason about your data the way an analyst would after a day on the job.

What's auto-generated

Object Info is generated for you. For a table or model that means:

• Identity: the name, type (table / model), source name, primary key.
• Fields table: every column with its type, nullability, a generated description if you didn't provide one, and a sample enum if the values are low-cardinality. Each field gets a role inferred from name and type (identifier, dimension, time, attribute, measure-candidate).
• For models: the SQL fragment that defines the model, the upstream sources, and any structural notes (composite grain, fan-out collapse).
• For contracts: the bounded interface, the measures, dimensions and filters it exposes, and an explicit note about what it does NOT support.
• For collections: the member objects and any connections between them inferred from shared field names.

You don't edit these. They're regenerated from the current state each time context is rebuilt; manual edits will be overwritten.

What you write

Two things, both optional but both high-value:

Field-level descriptions. Inside the Fields table, the Description cell for each column is yours. If a column name is unobvious (customer on raw_orders doesn't tell anyone it's per-ticket), write the description once and it's there for every agent and every chat session that touches this table. Same for the Enum cell when the schema doesn't carry enum values but the data has known categories.

The Business Context section. This is where you put everything that isn't in the schema:

• Terms: business vocabulary mapped to the data (ticket = order, basket size = count of items per order).
• Rules: invariants and gotchas (order_total = subtotal + tax_paid, always; Portland stores are tax-free and that's intentional, not bad data).
• Use cases: the analyses this dataset actually supports (daily revenue trend by store, hour-of-day demand curve, repeat-customer retention).

The Business Context section feeds the AI surfaces directly. Long, vague, or generic prose hurts you here: an agent has to read all of it. Aim for short, dense, specific.

The silently-dropped trap

The Business Context section has a recognized structure. The system reads Terms, Rules, Use Cases, and (for contracts) Measures, Dimensions, Filters. Anything outside those recognized headings is parsed but silently dropped during embedding.

That means a Business Context section that looks like this:

## Business Context

### Terms
- Ticket = order
- Basket = items on one order

### Retrieval Anchors                ← not recognized
- "revenue", "sales", "AOV"

### Query Patterns                   ← not recognized
- "Group by store_id for per-store breakdown"

…will only embed the Terms block. The other two headings, however helpful they look, contribute nothing to what an agent retrieves. They're not an error. They just don't exist as far as retrieval is concerned.

This is intentional: the recognized headings have stable semantics the system can index for retrieval. Ad-hoc sections can't, so they're skipped to keep retrieval consistent. The takeaway is operational: stay inside the recognized headings, or your prose isn't doing what you think it's doing.

The recognized headings differ by object type. The Context page lists them in the worked-example flow.

Stale headings don't break anything

If you've kept older context documents around with headings the current system doesn't recognize, that's fine. The document still parses; the stale sections just don't make it into retrieval. You can update them at your own pace.

How context reaches an agent

When an agent (or the chat surface) reasons about your data:

1. The agent issues a search for relevant objects. Gaur ranks tables, models, contracts, and collections by how well their context matches the question.
2. The top results are pulled with their full context attached.
3. The agent reads the Object Info to learn the schema and the Business Context to learn the meaning, then composes a contract query.

The contract still has the final word: nothing the agent reads from context lets it bypass cardinality validation or row-level security. See The contract model for the guarantee chain.

What good context buys you

• Right column, first try. With customer and customer_unique_id disambiguated, an agent counts customers, not tickets.
• Right contract. With each contract's purpose written down, an agent picks product_performance for SKU-level analysis instead of store_performance.
• Right caveats. With seasonality and ramp-up rules in the Business Context, an agent flags newly-opened stores instead of silently reporting them as underperforming.

Context isn't decoration. It's the thing standing between a confident, correct AI answer and a confident, wrong one.

Where to next