Using Guides to improve AI query accuracy and personalize agents

Preview

This feature is in preview and is subject to change.

With guides you capture the domain knowledge that isn't visible from a schema: how your org defines MRR, which tables to join on, which columns to avoid, common pitfalls in your data, or what "client" means in your field of work. Guides also work for personal preferences: your Dive styling, your Flight conventions, the way you like results formatted.

Guides are markdown documents you store in MotherDuck that AI agents read before working with your data. You write a guide once; from then on, every agent session picks it up automatically through the MCP server. No copy-pasting context into every chat over and over. Org-shared guides align every agent in your organization on the same definitions; private guides personalize agents to how you work.

Prerequisites

• A MotherDuck account with the MCP server connected to an AI client like Claude, Cursor, or Claude Code
• Permission to share org-wide guides (for publishing guides to your whole organization)

Organize guides with topics

Topics are an effective way for agents to discover guides without wasting tokens. Instead of loading every guide up front it calls list_guides(topic), the agent sees the topic tree with guide counts and drills into the topics that look relevant to the task. This is called progressive disclosure and works best when you:

• Pick descriptive topic names. The agent decides whether to open revenue-billing based on the name alone, so revenue-billing beats misc or team-docs.
• Keep the structure easy to traverse. A handful of well-named top-level topics with one or two levels below is easier to navigate than a deep or fragmented tree. Topics carry no uniqueness — any number of guides can share one.
• Reserve the root for truly general guides. Guides without a topic are listed individually in every get_query_guide overview: easiest for the agent to find, but they occupy space in every session. Leave the topic empty only for guides so general they don't belong to any specific domain, like a company description, unique attributes to the field the company operates in, a data platform overview or org-wide SQL conventions.

Use	Avoid	Why
revenue-billing	misc	Names the business domain the guide covers
revenue-billing/forecasting	revenue-billing/quarterly/q3/forecasting	Keeps the hierarchy shallow and easy to traverse
No topic for a data platform overview	No topic for an MRR definition	Reserves the root for guidance that applies across domains

Each guide has a unique identifier and carries an optional topic: a grouping label like revenue-billing. Topics can be nested with slashes, forming a hierarchy similar to folders in a filesystem: a guide with topic revenue-billing/forecasting lives inside revenue-billing, and opening revenue-billing also reveals its nested topics.

Personal and org-shared guides live in the same topic tree, the reserved dives and flights topics hold Dive and Flight conventions, and references link individual guides to the catalog objects they document:

Guide catalog

“Data platform overview”no topicorganization

revenue-billing/topic

“MRR and ARR Definitions”organization

→ references billing.main.subscriptions

“My revenue query snippets”user

forecasting/nested topic

“Forecast model inputs”organization

→ references Quarterly forecast Dive

dives/reserved · Dive conventions

“My Dive style”user

flights/reserved · Flight conventions

Personal (user) and org-shared (organization) guides sit in one topic tree. Topics group and nest like folders but carry no identity — every guide is addressed by its UUID. References (→) link a guide to the catalog objects, Dives, Flights, or guides it documents.

An agent can ask for an overview of all topics by calling get_query_guide. This lists every topic with its guide count followed by the guides stored at the root with their title, description, access level, and unique ID:

- data-quality/ (1 guide)
- revenue-billing/ (2 guides)
- revenue-billing/forecasting/ (1 guide)
- "Data platform overview" — what lives where in our warehouse (organization, uuid: a1b2c3d4-...)

note

The dives and flights topics are left out of this overview; they appear in their own entry points.

Using topics

Topics are like an index in the back of the book. These clues direct an agent to the right place to learn about your specific concepts, and it finds every guide filed there. Topics let the agent traverse the knowledge graph in a well-worn pattern and reliably retrieve the right information.

Topics should be concise and fit together in a coherent way. One way to structure them is shown below:

(no topic)              One orientation guide: the definitions an agent needs first,
                        per-schema notes, the join graph, and pointers to everything below
definitions/            A glossary of terms that maps common language to your data
<domain>/               How bundles of metrics are computed, one topic per area:
                        revenue-billing/, sales-funnel/, product-usage/
<database>/<schema>/    Information related to a specific database, schema, and so on

• The main guide sits at the root without a topic, so it is included in every get_query_guide overview. It should represent a map rather than a manual: things that are always needed for your agent to successfully return answers, and pointers to other guides and notes on when to use them.
• Mirror a tree you already navigate by. dbt project schemas make a good topic tree (dbt/<schema>/) because you already use them, which means the agent gets to share your reasoning "for free".

Governance for guides

Guides can have different levels of visibility: user or organization. Visibility is a per-guide property, independent of topic:

Access	Who can see it
user (default)	Private to the guide's owner
organization	Everyone in your MotherDuck organization (setting this is only available for organization admins)

There is no separate personal namespace: every listing and overview shows all guides visible to you — your private guides and org-shared ones overlaid in the same topic structure. A private guide with topic revenue-billing appears alongside the org's guides on that topic; each entry's access level tells you (and the agent) which is which.

The reserved dives and flights topics

The dives and flights topics extend the built-in Dive and Flight instructions. When an agent calls get_dive_guide before building a Dive, or get_flight_guide before authoring a Flight, the returned instructions end with an overview of your guides under that topic — so your conventions ride along with the product documentation the agent reads anyway.

Use them for:

• dives — personal or org-wide Dive styles: themes, color palettes, number formatting, layout preferences.
• flights — personal or org-wide Flight conventions and recipes: scheduling standards, naming rules, proven ingestion patterns worth reusing.

To have your assistant remember a personal style across sessions:

Create a Dive guide that says that I prefer dark-themed Dives with compact number formatting

The agent creates a private guide with topic dives and access user. Org-wide conventions use access organization instead. Because these topics are reserved, get_query_guide leaves them out of its overview — they only appear in their own entry points.

Create your first guide

The recommended way to create guides is through an AI agent. In Claude, Cursor, or another MCP-connected client, describe the guide you want:

Create an org-wide guide with topic "revenue-billing" that explains:
- MRR is calculated from the subscriptions table using status = 'active' and trial_end IS NULL
- ARR is MRR × 12
- The billing schema is in the billing database, main schema
- Never join subscriptions to invoices for revenue — use subscriptions directly

The agent uses the create_guide MCP tool. You can also create guides directly from SQL:

Creating a Guide

SELECT
  id,
  topic,
  current_version
FROM
  MD_CREATE_GUIDE (
    topic = 'revenue-billing',
    title = 'MRR and ARR Definitions',
    description = 'How monthly and annual recurring revenue are calculated',
    content = '
# MRR and ARR definitions

MRR is the sum of all active subscription amounts normalized to a monthly value.

Key rules:
- Use the subscriptions table, not invoices
- Filter to status = active
- Exclude trial subscriptions (trial_end IS NULL)
',
    access = 'user'
  );

SQL Editor loading...

Login to connect

PreviewLogin for live results

The returned id is the guide's permanent identifier — all later reads and updates use it. A one-line description pays off twice: it shows up in topic overviews (helping the agent decide what to read) and it's matched by catalog search.

tip

Bootstrapping a whole organization rather than one guide? Bootstrap Guides from the context you already have is a prompt that walks an agent through harvesting definitions out of your Slack threads, dbt project, and query history, then validating them with you before they're saved.

Browse and read guides

To see what guides exist, ask your AI agent:

What guides does my organization have?

The agent calls list_guides, which lists the catalog level by level: guides at the current level plus nested topics with their guide counts. You can also run the SQL function directly:

SELECT id, topic, title, description, access FROM MD_LIST_GUIDES();

Filter to a topic subtree — topic = 'core' matches core and core/metrics, but not core-metrics:

SELECT id, title FROM MD_LIST_GUIDES(topic = 'revenue-billing');

Read a guide in full by ID:

SELECT title, content
FROM MD_GET_GUIDE(id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890');

Every update creates a version snapshot. Browse the history with MD_LIST_GUIDE_VERSIONS(id = ...) and read an older version with MD_GET_GUIDE(id = ..., version = 2).

Update a guide

For large changes, replace the full content:

Update the MRR guide to add a section on expansion MRR

The agent calls update_guide, or you can run it directly:

SELECT current_version
FROM MD_UPDATE_GUIDE(
  id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  content = '...(full updated markdown)...',
  change_comment = 'Add expansion MRR section'
);

For targeted edits (fixing a table name, correcting a value), the agent uses edit_guide_content, which applies find-and-replace edits without resending the whole document:

Rename billing.main.orders to billing.main.customer_orders in the MRR guide

To retitle a guide or move it to a different topic without touching the content, use update_guide_metadata:

SELECT topic, title
FROM MD_UPDATE_GUIDE_METADATA(
  id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  topic = 'customer-orders',
  title = 'Customer Order Filters'
);

Attach references to a guide

References are a powerful way to make sure the agent finds the right object. It links a guide to the specific catalog objects, Dives, Flights, or other guides it documents. They power the automatic surfacing: when the agent calls list_tables on a database, the guides referencing objects in that database come back with the result (including databases attached as shares).

References can target a whole table or narrow down to a single column:

SELECT current_version
FROM MD_UPDATE_GUIDE(
  id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  "references" = [
    {
      'type': 'catalog',
      'url': 'md:billing',
      'schema': 'main',
      'table': 'subscriptions',
      'description': 'Primary source for subscription revenue data'
    },
    {
      'type': 'catalog',
      'url': 'md:billing',
      'schema': 'main',
      'table': 'subscriptions',
      'column': 'amount',
      'description': 'Monthly subscription amount in cents'
    }
  ]
);

For a database attached as a share, use the share URL instead of the database name — list_databases or MD_ATTACHED_DATABASES shows the URL for each attached database:

SELECT current_version
FROM MD_UPDATE_GUIDE(
  id = 'b2c3d4e5-f6a7-8901-bcde-f12345678901',
  "references" = [
    {
      'type': 'catalog',
      'url': 'md:_share/sample_data/23b0d623-1361-421d-ae77-62d701d471e6',
      'schema': 'hn',
      'table': 'hacker_news',
      'description': 'Hacker News sample data shared by MotherDuck'
    }
  ]
);

Then find relevant guides before writing a query:

SELECT id, title
FROM MD_LIST_GUIDES(
  reference = {
    'type': 'catalog',
    'url': 'md:billing',
    'schema': 'main',
    'table': 'subscriptions'
  }
);

How agents interact with guides

Guides are directly integrated into the MotherDuck MCP server. The MCP already exposes tools to search, query, and create Dives and Flights. For each of these tools your agent gets a nudge to check for any relevant Guides.

Tool used by the agent	Guide surface
query	The tool description nudges the agent to call get_query_guide before writing SQL to answer a data question
get_query_guide	Navigation instructions plus an overview of all personal and organizational guides: every topic with its guide count, and the root-level guides in full
search_catalog	Guides whose topic, title, or description match the search query appear as relatedGuides next to the catalog hits
list_tables	Guides that reference any object in the listed database are appended to the result
get_dive_guide	The Dive instructions end with an overview of the guides under the reserved dives topic
get_flight_guide	The Flight instructions end with an overview of the guides under the reserved flights topic

So even when an agent skips the entry point and jumps straight into catalog search or table exploration, it still stumbles over the guides that matter for the task at hand. From any of these surfaces, the agent reads a guide in full with get_guide and browses further with list_guides.

Tips for effective guides

• One subject area per topic. Group related guides under a shared topic — revenue-billing, user-events, data-quality — so the agent can open the right topic from the name alone.
• Write descriptions. The title and description are all the agent sees before deciding whether a guide is worth reading, and they're what catalog search matches against.
• Lead with rules, not explanations. Write Use subscriptions, not invoices rather than a paragraph explaining the data model history. Agents read guides under context-window pressure.
• Include working SQL patterns. Copy-paste-ready SQL is more useful than prose descriptions of what to query.
• Name pitfalls explicitly. Never join X to Y or Exclude rows where Z prevents systematic errors.
• Use references. Most importantly, reference the database or share a guide is about — any catalog reference into a database makes the guide surface in list_tables when the agent explores it. Narrow references down to tables or columns when the guide covers specific objects.
• Version comments tell the story. Use change_comment to explain why a guide changed, not just what changed. For example: Switch from invoices to subscriptions table after data model migration.

Manage guide visibility

By default, guides are private (access = 'user'). With admin permission, you can make a guide visible to the whole organization:

SELECT access
FROM MD_SET_GUIDE_ACCESS(
  id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  access = 'organization'
);

Delete a guide

Deleting a guide removes it from the active catalog but preserves its version history internally. Only the guide's owner can delete it:

SELECT success
FROM MD_DELETE_GUIDE(id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890');

References from other guides to a deleted guide are left dangling — clean them up in the referencing guides if needed.

Related resources

• Bootstrap Guides from the context you already have — A prompt that harvests guides from Slack, dbt, and query history
• MCP tool reference — Guides — Full reference for each guide MCP tool
• SQL function reference — Guides — Full reference for each MD_*_GUIDE SQL function
• MCP workflows — Tips for working with the MotherDuck MCP server