What is a context document
The document that teaches AI how to understand your data.
- Understand the role of the context document
- Recognize a good context vs a bad one
- Knowing what to put in it
Imagine hiring someone who is brilliant at SQL but has never heard of SQL.
your company. She knows how to join tables and add columns, but she doesn't do it.
idea of what mrr means, if
status = 2 means "active" or "cancelled", nor who
counts as a customer. Before giving any useful answer, she needs to
Let someone explain the deal. One
context document serves exactly that purpose, writing
once and handed it to the AI every time it queries your data.
He lives in Semantic Layer, the layer that gives meaning to the tables, and is read by the AI agent (via MCP) along with the schema. But be careful: the context document does not repeat the what your tables and columns are. This already lives elsewhere.
Where everything lives: Catalog and context document
The description of tables and columns (what the given is) you write directly to the Nekt Academy, field by field. O context document keeps the rest: like yours business works. Rules that do not appear in column none, such as revenue recognition, customer definition asset, the criteria for each stage of the funnel and the specific rules that must be considered in each analysis.
| Column | Description |
|---|---|
id int |
Unique subscription identifier |
status int
|
1 = active, 2 = cancelled, 3 = overdue |
mrr decimal
|
Monthly recurring revenue, in BRL |
cliente_id int
|
Reference to the customer who owns the subscription |
We consider any subscription with paid status and at the same time to be an active customer. least one confirmed payment. Trials canceled like never before paid do not count. Revenue is recognized from the date of financial cut.
assinaturas.statuspagamentos
Why does this matter
Without context, the AI has to guess. She sees a column called
mrr and guess it's monthly income, see
cliente_ativo and invents what "active" means, finds
status = 2
and crosses your fingers. Every guess is a chance for a wrong answer, and to
getting closer still spends more tokens exploring the table. With
context, it answers right the first time and cheaper, because the
meaning has already been chewed up.
Anatomy of a context document
At Nekt, a context document combines two things that work together:
| Part | What is |
|---|---|
| Prose | Explanations in simple language, the way you would explain rule to a new analyst on the first day |
| Notes | Prose links to workspace resources: tables, fields, layers, queries, notebooks and sources |
The magic is in the notes. When the agent reads the document, each annotation resolve for the resource name and description which she points out. Thus the prose (the business context) and the schema (the technical context) reach the AI in the same package, without it having to leave hunting down which table or column you are talking about.
A good context document in practice
See a short example of the "Active Customer" concept. Notice how the prose loads the rule and the annotations point to the concrete resources.
We consider active customer every subscription with paid status and at least one confirmed payment. Trials canceled Those who never paid do not count. Revenue is recognized from the cut-off date defined by the finance company.
Notes that prose resolves
| Mention in prose | Solve for |
|---|---|
| "signature" |
gold.assinaturas · one line per signature
|
| "paid status" |
gold.assinaturas.status · 1 = active, 2 =
canceled
|
Nekt offers ready-made templates for the concepts that almost every company needs to describe:
| Template | What it documents |
|---|---|
| Revenue and MRR | How revenue is recognized, the calculation of MRR and the treatment of multiple currencies |
| Active customer | Which statuses count as paying and what is left out |
| Funnel Steps | The MQL, SAL and SQL criteria |
| Product use | Unit conversions and limits for each plan |
| Cross-cutting rules | The gotchas that apply to all analysis: exclusions, soft deletes, coins |
Describe what the metric means, not like her has been implemented. The schema changes over time, the definition remains. Keep each document focused on a single concept and, rather than repeat the same rule in several places, cross references between documents. A "Revenue" document may point to the "Active Client" instead of recopying the entire definition.
A SaaS had an agent who got every business question wrong. They asked "how many active customers do we have" and he counted lines of the customer table, including canceled trials and accounts test. After an "Active Customer" context document (with the rule "active = paid subscription with usage in the last 30 days" and notes pointing to the subscription table and status field), the The same agent started to get it right. Nothing has changed in the data, only the meaning became explicit.