Using Guides to improve AI query accuracy and personalize agents

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

When an agent calls get_query_guide, it receives the root-level Guides and a hierarchy of topics with their Guide counts. Use that structure to separate general orientation from context that applies only to a specific task:

• Keep one orientation Guide at the root. Root-level Guides appear in every overview. Include information every agent working with your organization's data should know, such as what each database contains, organization-wide SQL conventions, and important terminology.
• Put narrower Guides under topics. Definitions and instructions that apply to one domain, metric, database, or schema should load only when they're relevant.
• Use descriptive topics. Topic names such as revenue-billing and sales-funnel help the agent decide where to look. Several related Guides can share a topic. Add a nested topic for a meaningful subgroup, such as revenue-billing/forecasting for forecasting Guides within the broader revenue domain.
• Reuse a structure your team knows. For example, mirror the domains or schemas in your dbt project instead of creating another taxonomy.

For example:

revenue-billing/
  Subscription revenue     MRR and ARR definitions, source tables, and filters
  Collections              Invoice, payment, refund, and delinquency rules
  Customer identity        Account mappings used by both workflows
revenue-billing/forecasting/
  Subscription forecast    Forecast inputs and scenario conventions

Use	Avoid	Why
revenue-billing	misc	Names the business domain the Guide covers
revenue-billing/forecasting	revenue-billing/forecasting/subscription-forecast	Groups related Guides instead of creating a topic for one Guide
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-...)

The topic hierarchy isn't the only way an agent finds Guides. Catalog search matches Guide topics, titles, and descriptions. Database exploration also returns Guides that reference objects in that database. See How agents interact with Guides for all discovery paths.

note

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

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.

Guides behind a service-account connection

When your application connects through a service account, access: "user" means private to that service account. If several end users share its connection identity, those Guides are shared context for those users. A topic name doesn't provide an additional access boundary.

For one service account per tenant, use private Guides for tenant definitions and keep individual preferences scoped in your application. Avoid organization-wide Guides for tenant-specific content when several tenants share one MotherDuck organization. See Personalize answers with Guides for a wrapper pattern.

The reserved dives and flights topics

Two topic names are reserved. Guides under dives extend the built-in Dive instructions, and Guides under flights extend the built-in Flight instructions. get_query_guide leaves both topics out of its overview because they're available through their respective authoring tools.

See Add Dive styles and Flight conventions to create and test one.

Turn a working session into a Guide

After a session where you corrected an agent's assumptions, explained which table to trust, or worked through a join that isn't obvious from the schema, ask it to save that context:

Turn all the durable business and data context we've established in this
conversation into a private MotherDuck Guide. Capture definitions, trusted
tables, join and filter rules, and pitfalls — methods, not one-time results.
Show me the proposed title, description, topic, and content before saving.

The agent creates a private Guide with access user. Create your first Guide from a chat session explains how to review and test it.

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. Later reads and updates use it. Write a one-line description that identifies the Guide's scope; descriptions appear in topic overviews and are matched by catalog search.

tip

Create your first Guide from a chat session captures context you've already given an agent. To build a larger set of Guides from Slack, dbt, and query history, use Bootstrap Guides from the context you already have.

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 link a Guide to the catalog objects, Dives, Flights, or other Guides it documents. When an agent calls list_tables on a database, the result includes Guides that reference objects in that database, 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

MotherDuck MCP tools surface Guides through several discovery paths:

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

From any of these results, the agent reads a Guide in full with get_guide and browses a topic with list_guides.

Guides and column comments

Use COMMENT ON for concise object metadata and Guides for broader context:

	COMMENT ON	Guide
Scope	One table, view, or column	A domain, metric, or convention that spans objects
When the agent reads it	On every schema introspection	When a topic, description, or reference matches the task
Right length	A sentence	As long as the subject needs
Right content	What the object is, valid values, the join key	Why one table is trusted over another, how a metric is computed, what never to do

Agents read comments on every schema introspection. Keep comments to one sentence and move longer business context into a Guide:

COMMENT ON COLUMN subscriptions.status IS 'Subscription state: active, trialing, past_due, canceled. Revenue rules are in the MRR and ARR Definitions Guide.';

The comment can name the Guide that contains the full context.

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