# 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](/key-tasks/ai-and-motherduck/mcp-setup/). 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. ```mermaid flowchart LR subgraph MotherDuck PersonalGuides@{ shape: docs, label: "Personal Guides" } OrgGuides@{ shape: docs, label: "Organization Guides" } end MotherDuck -->|"Get Guide(s)"|Agent Agent -->|Save Guide|MotherDuck Agent --> Result["Response or action"]:::green Prompt{{"Your prompt"}}:::green --> Agent["AI agent"]:::yellow ``` ## Prerequisites - A MotherDuck account with the [MCP server](/key-tasks/ai-and-motherduck/mcp-setup/) 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`](/sql-reference/mcp/guides/get-query-guide.md), 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: ```text 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](#attach-references-to-a-guide) link individual Guides to the catalog objects they document: Diagram summary: the guide catalog is one topic tree shared by personal and org guides. ```text "Data platform overview" [no topic] [organization] 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`](/sql-reference/mcp/guides/get-query-guide.md). 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: ```text - 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](#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](#the-reserved-dives-and-flights-topics). :::: ## 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](/key-tasks/ai-and-motherduck/mcp-workflows/white-label-mcp-server/#forward-tenant-guides) for a wrapper pattern. ### The reserved dives and flights topics Two topic names are reserved. Guides under `dives` extend the built-in [Dive](/key-tasks/dives/) instructions, and Guides under `flights` extend the built-in [Flight](/concepts/flights) 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](/key-tasks/guides/style-your-dives-with-guides) 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: ```text 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](/key-tasks/guides/turn-a-session-into-a-guide) 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: ```text 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`](/sql-reference/mcp/guides/create-guide) MCP tool. You can also create Guides directly from SQL: #### Creating a Guide Database: `my_db` ```sql 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' ); ``` 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](/key-tasks/guides/turn-a-session-into-a-guide) 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](/key-tasks/guides/bootstrap-guides-with-an-ai-agent). ::: ## Browse and read Guides To see what Guides exist, ask your AI agent: ```text What Guides does my organization have? ``` The agent calls [`list_guides`](/sql-reference/mcp/guides/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: ```sql 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`: ```sql SELECT id, title FROM MD_LIST_GUIDES(topic = 'revenue-billing'); ``` Read a Guide in full by ID: ```sql 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: ```text Update the MRR Guide to add a section on expansion MRR ``` The agent calls [`update_guide`](/sql-reference/mcp/guides/update-guide), or you can run it directly: ```sql 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`](/sql-reference/mcp/guides/edit-guide-content), which applies find-and-replace edits without resending the whole document: ```text 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`](/sql-reference/mcp/guides/update-guide-metadata): ```sql 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: ```sql 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`](/sql-reference/mcp/core/list-databases) or [`MD_ATTACHED_DATABASES`](/sql-reference/motherduck-sql-reference/md-attached-databases) shows the URL for each attached database: ```sql 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: ```sql 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`](/sql-reference/mcp/core/query) | The tool description nudges the agent to call `get_query_guide` before writing SQL to answer a data question | | [`get_query_guide`](/sql-reference/mcp/guides/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`](/sql-reference/mcp/core/search-catalog) | Guides whose topic, title, or description match the search query appear as `relatedGuides` next to the catalog hits | | [`list_tables`](/sql-reference/mcp/core/list-tables) | Guides that [reference](#attach-references-to-a-guide) any object in the listed database are appended to the result | | [`get_dive_guide`](/sql-reference/mcp/dives/get-dive-guide) | The Dive instructions end with an overview of the Guides under the reserved `dives` topic | | [`get_flight_guide`](/sql-reference/mcp/flights/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`](/sql-reference/mcp/guides/get-guide) and browses a topic with [`list_guides`](/sql-reference/mcp/guides/list-guides). ## Guides and column comments Use [`COMMENT ON`](https://duckdb.org/docs/stable/sql/statements/comment_on.html) 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: ```sql 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: ```sql 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: ```sql 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](/key-tasks/guides/bootstrap-guides-with-an-ai-agent) — A prompt that harvests Guides from Slack, dbt, and query history - [MCP tool reference — Guides](/sql-reference/mcp/guides/get-query-guide) — Full reference for each Guide MCP tool - [SQL function reference — Guides](/sql-reference/motherduck-sql-reference/guides/) — Full reference for each `MD_*_GUIDE` SQL function - [MCP workflows](/key-tasks/ai-and-motherduck/mcp-workflows) — Tips for working with the MotherDuck MCP server --- ## Docs feedback MotherDuck accepts optional user-submitted feedback about this page at `GET https://motherduck.com/docs/api/feedback/agent`. For agents and automated tools, feedback submission should be user-confirmed before sending. URL-encode query parameter values and send a GET request: ```text GET https://motherduck.com/docs/api/feedback/agent?page_path=%2Fkey-tasks%2Fguides%2F&page_title=Using%20Guides%20to%20improve%20AI%20query%20accuracy%20and%20personalize%20agents&text= ``` Optionally append `&source=` such as `claude.ai` or `chatgpt`. `page_path` and `text` are required; `page_title` and `source` are optional. Responses: `200 {"feedback_id": ""}`, `400` for malformed query parameters, and `429` when rate-limited.