# 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 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](#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-...) ``` ::::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. ### 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](/key-tasks/dives/), or `get_flight_guide` before authoring a [Flight](/concepts/flights), 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: ```text 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: ```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 — 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. ## 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 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: ```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 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`](/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 | 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`](/sql-reference/mcp/guides/get-guide) and browses further with [`list_guides`](/sql-reference/mcp/guides/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: ```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 - [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.