MotherDuck Guides: What to Put in Them, and What to Push Down

MotherDuck already gives an analytics agent most of what it needs. The MCP server connects a model like Claude directly to the warehouse, where it can inspect the catalog, run SQL, and check its own results. Table and column comments, fed from dbt through persist_docs, give the agent object-level context at the moment it reads a schema. Across our client base, that setup alone turns natural-language questions into correct SQL more often than most teams expect.

What that setup could not do was carry context that spans objects. A column comment can define what amount means; it cannot tell the agent which of three revenue source tables finance treats as the source of truth (or what combination of them). That knowledge is organizational, and it previously did not live anywhere accessible for an agent (unless you rolled your own company context server, which you likely should not do).

So we were glad when MotherDuck released Guides: markdown documents that live inside MotherDuck, which an agent reads from the MCP before it works with your data. MotherDuck positions them to capture the domain knowledge a schema cannot show and to align every agent on the same definitions. That is exactly the org-level layer we were missing.

Guides are a new feature, so there is no established practice for what to put in one. We had to work out how to write docs that would support the range of questions a client’s users ask. We started from the documentation the business already had: KPI definitions, metric logic, and source-of-truth notes. Then, we organized that context around how people query the MCP, using our existing agentic-analytics benchmark examples to trace the shapes of real questions. The last step mattered most: finding the gap between what MotherDuck already surfaced (the schema and its comments) and what a Guide would need to add.

Our first set of Guides overlapped heavily with the context the schema and comments already carried. The gains came from cutting that overlap. We set out to write exhaustive Guides, and the improvement turned out to be addition by subtraction: the second version was about a sixth the size of the first, and it produced better answers.

That result points at what a Guide is for: a Guide is a routing and context layer, not documentation. Its job is to get an agent to a correct answer in fewer tokens, not to be complete. Length is a cost the agent pays on every question where it accesses the Guide.

As of July 2026, Guides are a new MotherDuck feature, so treat what follows as early principles rather than settled practice. We built them from client work, and we expect to revise them as Guides integrate with the rest of MotherDuck’s AI-oriented documentation tools.

Figure 1: Agentic analytics ecosystem on MotherDuck. The agent reaches the schema and its comments through the MCP; Guides add the cross-object context those cannot carry, authored by the data team and grounded in business users’ knowledge.

Start from what the schema already does

Before you write a single Guide, measure what your schema already does on its own. The case for restraint is empirical.

MotherDuck’s Jacob Matson ran 500 questions from the BIRD benchmark against three frontier models (Claude Opus 4.5, GPT-5.2, and Gemini 3 Flash) with nothing but the schema. All three reached about 95% accuracy under realistic scoring. Adding a column comment to every table changed accuracy by roughly one point on the training split and almost nothing on the holdout. On the cleanest schemas the comments lowered accuracy, because they added noise the model did not need. That is his finding, and it should reset the instinct to document everything. Two caveats temper excitement with 95% accuracy: the missing points are confidently wrong answers rather than obvious failures, and with targeted context, the ceiling climbs toward the near-perfect accuracy on more complex schemas. This indicates the value of spending context where it counts, not everywhere.

The lesson carries straight into Guides. A clean data model with clear table and column names does most of the work an agent needs, which is the same governed model that keeps agents from querying raw sources and getting the wrong answer faster. Where a name is genuinely confusing, a targeted column comment through dbt persist_docs fixes it at the source, and that comment is testable and reaches the agent through the catalog. A Guide that restates what a column name (or column comment) already says wastes tokens while increasing risk.

If you do not already have a documented data model in place, Guides can serve as a proof of concept for adding context to the MCP to answer commonly asked questions. But if you already have a documented data model in place, a practice we recommend across our clients, ensure that the Guides you create add distinct value to the questions you ask of MotherDuck via the MCP.

Figure 2: Context discovery & surfaces. Push each fact down to the most testable layer that can contain it (the data model or persist_docs) and keep the thin Guides layer for context the schema cannot effectively communicate.

What only a Guide can communicate

Based on our initial experimentation, four kinds of knowledge belong in a Guide:

1. Which source is authoritative. When the same fact lives in three tables, the Guide names the one to trust and why the others exist. Without it, the agent picks by proximity and returns a defensible but inaccurate number.
2. How lightly modeled business concepts map to the data. Users ask about “pipeline,” but nothing is named that. It resolves to fct_opportunities, filtered to open stages, with closed-lost and sub-$1,000 deals dropped by convention. That mapping from a word to a table and its default filters is organizational, and a Guide is one place it can live. If you already embody data modeling best practices (i.e. entity models for core business entities, reporting models for validated company-level KPIs) and have successfully modeled across all relevant business domains, then “pipeline” might already live in the data model. If not, a Guide might direct the agent to the correct table + logic to indicate how “pipeline” should be calculated. Because there is a long tail of metrics, not all of which fall in the category of “KPIs”, it is reasonable to expect that some proportion of metrics will not reside in your data model. The Guide should contain high level information that directs the agent to the right approach.
3. How sources combine. Join paths, grains, and order of operations are rules the schema hints at but does not enforce. In one engagement, business lines were tracked differently across two ERP systems and a manufacturing management platform, so any breakout by business line meant reconciling three encodings first. The Guide records that reconciliation once, so the agent does not stitch the sources together in a plausible but wrong way.
4. Which numbers look similar but measure different things. Bookings and revenue, gross and net, shipped and invoiced: pairs an agent will treat as interchangeable unless told otherwise. The Guide flags the ones that must never be summed or compared.

That residual grows with complexity. The BIRD databases average about seven tables, with simple one-to-many joins and no many-to-many relationships. A real enterprise warehouse is the opposite. Even a simple client of ours runs past 20 tables, and most run into the hundreds, with overlapping sources, conflicting definitions, and business rules that live in people’s heads rather than in the DDL. Matson makes the same point: curated context starts to matter as domain rules get complex. MotherDuck’s Guides launch benchmark shows the payoff at that end. On DABStep, a set of multi-step questions built on real business rules, Guides raised agent accuracy by 72 percentage points over agents left to discover context on their own. The data leader’s warehouse is complex, which is why this layer is worth getting right.

The highest-value Guide is usually the cross-cutting one, the document that explains how those pieces relate. No single table contains that relational knowledge, so the schema can never supply it. If you write only one Guide, write that one.

Measure tokens-to-correct-answer, not coverage

The metric that changed our decisions is tokens-to-correct-answer: the context an agent spends to reach a correct result. Optimize that, not coverage. If a line does not change what the agent does next, cut it. Context is a finite resource, and good context engineering means fitting the right information, not the most.

On a mature data model, accuracy is not the variable to move. Our benchmark suite for this client, the same set we use to score data-model changes, was already near its ceiling before we wrote any Guides. So the Guide’s job was not a higher score. It was fewer tokens on the questions we already answer correctly, and better answers on the questions we have not seen. Measured against that suite, a lean Guide set cut tokens-to-answer by 30-64% and response time by 25-65% across different types of models and run parameters, with no loss of accuracy. The win is pure efficiency: the Guide routes the agent to the right model in fewer exploration turns.

Fewer tokens lowers cost and latency. It also raises accuracy. Model performance degrades as context grows, well before the window is full, and Chroma found the effect in all 18 frontier models it tested. Information buried in the middle of a long context is the least likely to be used at all. A leaner Guide is a more accurate Guide. On the same MotherDuck launch benchmark, Guides also cut cost per run by about 55%, which buys roughly twice the tokens for the same budget.

For context documentation, instructions perform worse than facts, and several short documents beat one long one. When an agent is asked to follow a long document, its compliance drops. HANDBOOK.md, a 2026 benchmark of agents following 20-to-124-page standard operating procedures over the MCP, found the best of thirty model configurations satisfied every rule on 36.2% of tasks, most stayed below 25%, and agents lost rule details over long horizons. A Guide can easily become a long set of instructions. The longer the agent runs, the less of the Guide it applies.

Do not hardcode answers to questions. A Guide that passes your known questions by hardcoding their specifics will fail the ones you have not seen, including a held-out test set. Measure whether the Guide generalizes to new questions, not whether it clears the benchmark you tuned it against.

Principles for Guides that generalize

A few principles enable a Guide to generalize to new questions:

Trust the runtime. Let the agent read its own catalog, tool list, and permissions. Those are per-user and they change, so the live environment is the source of truth, not your description of it. Route by the shape of the question rather than by who is asking, because assumptions about a person’s role or name overfit the Guide and age badly.

Design for change. Only list limitations that will last. “We cannot answer X” is inaccurate right after you deliver X, and it lingers in the Guide long after. Track missing capability as a backlog instead. Keep one-off specifics out too. A number or a name pulled from a single conversation teaches the agent about a past question, not about the system, unless the number itself reveals something structural.

Set the posture. A Guide states defaults, not laws, and it should say so, because the agent’s job is to answer the user, not to obey the Guide. Warn sparingly. MotherDuck’s finding that unnecessary comments lowered accuracy is a warning in itself: preemptive detail adds noise, and a list of “do not do X” expands context and typically adds limited value. Give the agent and your team a visible way to report a wrong or missing answer, so gaps become fixes rather than silent failures.

A Guide can be private to its author or shared across the whole organization. An org-shared Guide aligns every agent in the company on one definition of a domain, which is the point of it. It also means a wrong org Guide scales that error to everyone at once. Deciding what earns organization-wide status is your standard to set.

Structure Guides so the agent finds them

MotherDuck surfaces Guides to the agent through a few paths, and a little structure makes them findable.

Group Guides under shallow, descriptively named topics. We organized ours around the way people query, so the agent reads the topic tree and drills into what looks relevant, and a handful of clear top-level topics beats a deep or fragmented hierarchy. Write the title and one-line description in the vocabulary a real question uses, because those two lines are all the agent sees before it opens a Guide, and they are what catalog search matches. Attach references so a Guide surfaces automatically when the agent explores the database it documents. Keep one orientation Guide that points to the focused ones.

A wrong Guide is worse than none

A Guide is more dangerous than a document, because it enters every session with the weight of settled fact. A wrong line in a document misleads whoever reads that document. A wrong line in a Guide enters the context of every future question, where the model treats it as true and reasons from it. Bad context does not stay local. It propagates into the answers.

Treat a Guide like code. Mine the knowledge from where it already lives, author one subject at a time, and verify every claim and identifier against the live system before you publish. When a model or a metric changes, a stale Guide should fail a check, not quietly mislead an analyst. MotherDuck supports that directly: guides are created and managed through SQL functions, so you can keep them in git and run changes through CI.

Bootstrap your Guides with an agent, then subtract

Your existing documentation is the best raw material for Guides, and the fastest way to build a bad set. Data dictionaries, dbt docs, runbooks, and meeting notes all hold the knowledge a Guide needs. Hand them to an agent with no direction and it copies the extraneous detail straight in, and you are back to the bloated first draft.

Instead, give the drafting agent these principles first, then your context docs, then live access to your catalog through the MCP. Ask it to propose a starting set: one orientation Guide, the cross-cutting Guide, and a few topic Guides with references attached. Then do the part only you can do: subtract what the schema already says, verify every identifier against the live system, and decide what earns organization-wide status. MotherDuck publishes a bootstrap framework for that first pass; the part it leaves to you is discretion.

A thin, correct routing layer is what makes an agent plus your data trustworthy, and if it is well designed, it should update relatively infrequently. Start with your ten most common questions, write the orientation Guide and the cross-cutting Guide, and measure the tokens before and after.

These are early principles for a new feature, and we will revise them as the tooling matures. If you want help building or auditing the context layer behind your analytics agent, let’s talk.

Sources

• Your Data Model Is the Semantic Layer. Jacob Matson, MotherDuck, February 2026. Source for 95% realistic text-to-SQL accuracy on 500 BIRD Mini-Dev questions across three frontier models with the schema alone, and for column comments adding about 1.1 points on train and 0.2 on test while lowering accuracy on clean schemas.
• Using Guides to improve AI query accuracy and personalize agents. MotherDuck documentation. Source for guide mechanics: topics and progressive disclosure, descriptions as the routing signal, references, and user and organization access levels.
• Effective context engineering for AI agents. Anthropic, September 2025. Source for context as a finite resource and for fitting the right information rather than the most.
• Context Rot: How Increasing Input Tokens Impacts LLM Performance. Chroma, 2025. Source for accuracy degrading with input length across all 18 frontier models tested, before the context window fills.
• Lost in the Middle: How Language Models Use Long Contexts. Liu et al., Transactions of the Association for Computational Linguistics, 2024. Source for information in the middle of a long context being the least likely to be used.
• Can LLM Already Serve as a Database Interface? A Big Bench for Large-Scale Database Grounded Text-to-SQLs (BIRD). Li et al., NeurIPS 2023. Source for the BIRD benchmark and for real databases requiring external knowledge beyond the schema.
• How Long Contexts Fail. Drew Breunig, June 2025. Source for context poisoning and how a wrong fact in context propagates into later answers.
• HANDBOOK.md: A Benchmark for Long-Context Agentic Instruction Following. Panavas et al., 2026. Source for agents following 20-to-124-page policy documents over the MCP satisfying every rule on at most 36.2% of trials, most below 25%, and losing rule details over long horizons.
• Context belongs in the warehouse. Ulmer, Döhmen, Matson, and O’Brien, MotherDuck, July 2026. The Guides launch announcement. Source for the DABStep results (Guides raised agent accuracy by 72 percentage points and cut cost per run by about 55% versus agents discovering context on their own, with Gemini 3 Flash answering 417 of 419 held-out questions correctly), and for managing guides through SQL functions and the bootstrap framework.