# create_guide > Create a new Guide — a markdown document that AI agents use to answer your organization's data questions correctly Create a new [Guide](/key-tasks/guides/) — a markdown document that captures metric definitions, join conventions, and domain context for your organization's data. ## Description The `create_guide` tool creates a guide identified by a generated UUID. Group related guides with an optional lowercase kebab-case `topic` (for example `"revenue-billing"` or `"core/metrics"`); omit it to keep the guide at the root level without a topic. Topics are grouping labels only — they carry no uniqueness, so multiple guides can share the same topic. Visibility is controlled by `access`: `"user"` (private, default) or `"organization"` (org-wide, admin-permission gated). Personal Dive and Flight style guides belong under topic `"dives"` or `"flights"` with access `"user"` — they're surfaced by [`get_dive_guide`](/sql-reference/mcp/dives/get-dive-guide) and [`get_flight_guide`](/sql-reference/mcp/flights/get-flight-guide). Attach `references` to link the guide to the 1–5 catalog objects, Dives, Flights, or other Guides it is authoritative about. References let [`list_tables`](/sql-reference/mcp/core/list-tables) and [`search_catalog`](/sql-reference/mcp/core/search-catalog) surface related guides automatically. ## Input parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `title` | string | Yes | Human-readable title. Must not be empty. | | `content` | string | Yes | Full markdown body of the guide. Maximum 1 MB. | | `topic` | string | No | Slash-separated grouping label — for example `"revenue-billing"` or `"core/metrics"` (no leading or trailing slash). Omit for no topic. | | `description` | string | No | Short one-line summary shown in the guide index. | | `access` | string | No | `"user"` (private, default) or `"organization"` (org-wide, admin-permission gated). | | `change_comment` | string | No | Optional note describing this initial version. | | `external_id` | string | No | Optional caller-provided ID for this version (for example a git SHA). | | `references` | array | No | Structured references to the 1–5 objects this guide explains. See [reference object shape](#reference-object-shape). | ### Reference object shape | Field | Type | Required | Description | |-------|------|----------|-------------| | `type` | string | Yes | One of `"catalog"`, `"dive"`, `"flight"`, or `"guide"` | | `url` | string | Conditional | MotherDuck URL — required for `catalog` type (for example `"md:my_database"` or a `"md:_share/..."` URL) | | `schema` | string | Conditional | Schema name — required when `table`, `view`, or `macro` is set | | `table` | string | No | Table name (catalog only) | | `column` | string | No | Column name (catalog only, requires `table`) | | `view` | string | No | View name (catalog only, mutually exclusive with `table`/`macro`) | | `macro` | string | No | Macro name (catalog only, mutually exclusive with `table`/`view`) | | `uuid` | string | Conditional | UUID of the referenced Dive, Flight, or Guide | | `description` | string | No | Why this reference exists | ## Output schema ```json { "success": boolean, "guide": { "id": string, // Generated UUID of the guide "topic": string, // Grouping label (null if omitted) "title": string, // Guide title "description": string, // One-line summary "access": string, // "user" or "organization" "current_version": number, // Version number (1 for new guides) "created_at": string, // ISO 8601 creation timestamp "updated_at": string, // ISO 8601 last update timestamp "version_change_comment": string, "version_external_id": string, "version_created_at": string, "references": array // Resolved references }, "error": string // Error message (on failure) } ``` ## Example usage **Create an org-wide metric definition guide:** ```text Create a guide explaining how we calculate MRR for the billing team ``` ```json { "title": "MRR and ARR Definitions", "topic": "revenue-billing", "description": "How monthly and annual recurring revenue are calculated", "access": "organization", "content": "# MRR and ARR Definitions\n\nMRR (Monthly Recurring Revenue) is the sum of all active subscription amounts normalized to a monthly value.\n\n## Key rules\n\n- Use the `subscriptions` table, not `invoices`\n- Filter to `status = 'active'`\n- Exclude trial subscriptions (`trial_end IS NULL`)", "references": [ { "type": "catalog", "url": "md:billing", "schema": "main", "table": "subscriptions", "description": "Primary source for subscription revenue data" } ] } ``` **Save personal Dive style preferences:** ```text Remember that I prefer dark-themed Dives with the watermelon accent color ``` ```json { "title": "My Dive style preferences", "topic": "dives", "access": "user", "content": "## Style preferences\n\n- Dark theme by default\n- Watermelon accent color\n- Number formats: compact notation (1.2M, not 1,200,000)" } ``` ## Success response example ```json { "success": true, "guide": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "topic": "revenue-billing", "title": "MRR and ARR Definitions", "description": "How monthly and annual recurring revenue are calculated", "access": "organization", "current_version": 1, "created_at": "2025-06-01T10:00:00Z", "updated_at": "2025-06-01T10:00:00Z", "version_change_comment": null, "version_external_id": null, "version_created_at": "2025-06-01T10:00:00Z", "references": [ { "type": "catalog", "url": "md:billing", "schema": "main", "table": "subscriptions", "description": "Primary source for subscription revenue data" } ] } } ``` ## Related - [`list_guides`](../list-guides) — Browse existing guides before creating one. - [`get_guide`](../get-guide) — Read a guide's content. - [`update_guide`](../update-guide) — Append a version to an existing guide. - [`edit_guide_content`](../edit-guide-content) — Make targeted in-place edits. - [Guides how-to](/key-tasks/guides/) — Step-by-step instructions for creating and managing Guides. --- ## 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=%2Fsql-reference%2Fmcp%2Fguides%2Fcreate-guide%2F&page_title=create_guide&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.