Analytics agents are still eager interns

Anyone who has used an agent to explore data knows that the agent is trying its best; it'll exhaustively look up schemas, infer join relationships itself, and tirelessly push for an answer that sounds decisive, appears well-presented, and is often totally, dangerously wrong. AI models struggle with the tradeoff between "achieving" a goal, even if wrong, and getting you the right answer more thoughtfully. It gets worse the more complex a data warehouse becomes.

We've certainly felt this analyzing our own business in MotherDuck, and our customers feel it in theirs. They're trying just about everything they can to steer agents in the right direction, from team-level skills, custom MCP servers, overloading DuckDB's COMMENT ON functionality, you name it. Everyone hates this state of affairs.

Regardless of the inquiry or task, the path to decision-making cuts through querying a data warehouse, so why not put the context there too, queryable in SQL?

Crossing the context chasm

Enter Guides: markdown files with a title and description, much like an agent skill. We believe that the warehouse, not a BI tool or point solution, is the rightful home for every piece of context about a business, both structured and unstructured. Guides live in your warehouse, versioned and queryable like any other object.

1. Accurate search and retrieval. Guides can programmatically reference your catalog, Dives, Flights, and even other Guides, so any lookup queries can automatically find the right Guide. Topics further improve agent search over tens or hundreds of Guides.
2. Automatic distribution. Guide ownership comes in two layers: organizational and user-level. Org-level updates are automatically propagated, ensuring metric definitions stay consistent. User-scoped Guides allow individuals to cultivate private versions for exploration, style consistency, or other personal preferences.
3. SQL-based management. Guides can be called and managed entirely with SQL through any MotherDuck client, which simplifies version control and CI.

So what goes in a Guide? Virtually everything an agent needs to know to be trusted with your data: metric definitions and join relations, the gotchas and caveats that currently live in your team's heads or in a Slack thread, and style guidance for Dives, our agent-native visualization tool, and conventions for Flights, our hosted Python runtime for building data pipelines.

For example, this Guide contains context about how to calculate fees, given a set of duplicated transactions in a table:

Copy code
---
id: fees-formula
domain: fees
summary: The fee formula and the dedupe-by-fee-id rule when averaging fees.
---
**Fee formula (per matching rule, per transaction):**
```
fee = fixed_amount + (rate / 10000.0) * eur_amount
```
`rate` is in basis points, so divide by 10000. `fixed_amount` and `eur_amount`
are euros.

- **Totals** (e.g. "total fees a merchant paid"): sum `fee_amount` over every
  matching (transaction × rule) pair. A transaction matching 3 rules contributes
  3 fees.
- **Averaging across fee rules** (e.g. "average fee the card scheme would charge
  for a transaction of V eur"): a single fee `ID` always has the same
  `fixed_amount` and `rate`, so **deduplicate by fee `ID` first**, then average
  over the distinct rules. Don't average over duplicated rows.
- For abstract "for a transaction value of V eur" questions there is no real
  transaction, so substitute the literal V into the formula:
  `fixed_amount + rate / 10000.0 * V`.

See `sql-avg-fee` and `sql-total-fees-merchant` for worked templates.

Guides follow your data, not your agent harness. If you switch between Claude, Codex, or any other harness, Guides just need access to the MotherDuck MCP server for an agent to start using them.

Benchmarking improvements

We put Guides to the test on DABStep, a public benchmark of multi-step data-analysis questions. Giving an agent Guides as context increased its answer accuracy by 72 percentage points and cut the cost per run by 55%.

With Guides, a small, fast model (Gemini 3 Flash) answered 417 of 419 held-out questions correctly, 99.5%, at about two cents per question. The setup is simple: a compact skill that teaches the agent where knowledge lives, plus a context layer of Guides it loads only as each question needs them.

Aside from the obvious improvements on accuracy, the cost delta is striking. At 55% lower cost per run, the same budget buys roughly twice the tokens: longer tasks, more feedback turns. Adding context with Guides delivers improvements far greater than simply plugging in the latest frontier model, not to mention the latency budget preserved in using a smaller, faster model.

You can learn more about the benchmark and reproduce it here.

Getting started with Guides

Like our other agent-native tools (Flights, Dives), Guides are designed with the MotherDuck MCP Server as the first-class interface for creation, updates, and management. You can use MCP clients like Claude, Codex, and Cursor to interact with Guides; the MCP Server will use them by default.

The fastest way to improve agent performance with Guides is to bootstrap: distilling context from your business into an essential set of Guides. This resource provides a framework for shaping an initial corpus of context into useful Guides. Simply connect your MCP-enabled agent and point it at the docs page to get started.

You can also manage Guides through the built-in SQL functions (e.g. MD_CREATE_GUIDE()). This enables source control with git, as we've documented in this example. Govern context in a GitHub repository, then use the SQL functions in CI to execute changes.

Happy guiding!