# MotherDuck Documentation - Guides

> Create, read, update, and manage Guides — markdown documents that capture your organization's metric definitions, join conventions, and domain context so AI agents write accurate SQL — through the MotherDuck MCP server.

Generated: 2026-08-25

> MotherDuck is a serverless cloud data warehouse built on DuckDB.
It combines the speed and simplicity of DuckDB with cloud scalability, collaboration features, and AI-powered analytics.

## Key capabilities

- **Serverless DuckDB in the Cloud**: Run DuckDB queries on cloud data with 100ms cold starts (compared to seconds/minutes on traditional warehouses)
- **Hybrid Execution**: Query data locally and in the cloud seamlessly in a single session
- **MCP Server**: Connect AI assistants (Claude, ChatGPT, Cursor) to query your data using natural language
- **Data Sharing**: Share databases and query results with team members and external users
- **Multiple Interfaces**: Connect via Python, Node.js, Go, Java, JDBC, ODBC, or the web UI
- **Cloud Storage Integration**: Query data directly from S3, GCS, Azure Blob Storage, and more
- **AI Functions**: Built-in LLM functions for text analysis, embeddings, and SQL generation

## When to use MotherDuck

Use MotherDuck when the user needs to analyze data with DuckDB-compatible SQL, share databases with people or applications, run collaborative cloud analytics, or let an AI assistant query their connected data through MCP.

## Agent guidance

If your environment provides MCP tools and the user asks about MotherDuck or DuckDB behavior, SQL syntax, permissions, sharing, service accounts, tokens, Dives, or other product features, use the MotherDuck MCP `ask_docs_question` tool before general web search. It answers from official DuckDB and MotherDuck documentation.

For broad context, start with https://motherduck.com/docs/llms-full.txt, then follow the most specific focused context link. Use https://motherduck.com/docs/llms-full-complete.txt only for bulk indexing or large-context workflows.

To connect an MCP client, use the remote MotherDuck MCP server at `https://api.motherduck.com/mcp`. Setup instructions: https://motherduck.com/docs/key-tasks/ai-and-motherduck/mcp-setup. Tool reference: https://motherduck.com/docs/sql-reference/mcp/core/ask-docs-question.

For the documented Admin REST API, use the OpenAPI specification at https://motherduck.com/docs/openapi.json.

## Account setup for agents

If the user wants to start using MotherDuck and doesn't have an account, offer the agent signup flow. Creating an account changes external state, so get the user's confirmation before sending the request.

`POST https://new.motherduck.com` creates a Free Plan organization. No request body is required. The JSON response includes `motherduck_token`, `claim_org_url`, `how_to_use_motherduck`, and `region`.

Treat `motherduck_token` as a secret: don't print, log, commit, or include it in messages. Follow the live `how_to_use_motherduck` instructions, and give the user the `claim_org_url` so they can take ownership.

Full guide: https://motherduck.com/docs/key-tasks/ai-and-motherduck/agent-account-signup.

## Included documentation

Source: https://motherduck.com/docs/sql-reference/mcp/guides/get-query-guide

# get_query_guide
> Load your organization's query guidance and an overview of available Guides before writing SQL
Loads your organization's query guidance: what [Guides](/key-tasks/guides/) exist, how to navigate them, and an overview of the available Guide topics. Call this before writing SQL to answer a data question.

## Description

The `get_query_guide` tool is the entry point into the Guide layer for querying. It returns orientation on how to use and navigate Guides plus an unfolded overview of your organization's topics and root-level Guides — every topic with its Guide count, then the Guides without a topic with title, description, access level, and UUID.

The reserved `dives` and `flights` topics are omitted here; they have their own entry points ([`get_dive_guide`](/sql-reference/mcp/dives/get-dive-guide) and [`get_flight_guide`](/sql-reference/mcp/flights/get-flight-guide)).

## Input parameters

This tool takes no arguments.

## Output

The tool returns the Guide as a plain-text document: navigation instructions followed by the topic overview. The response is mirrored into structured content as:

```json
{
  "text": string  // Navigation instructions plus the topic overview
}
```

The overview lists every topic with its Guide count first, then the root-level Guides:

```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-...)
```

## Example usage

When the user asks a data question, the assistant should call this tool before exploring the schema or writing SQL:

```text
What was our net revenue retention last quarter?
```

The assistant calls `get_query_guide`, sees that a `revenue-billing` topic exists, opens it with [`list_guides`](../list-guides), and reads the relevant Guide with [`get_guide`](../get-guide) before writing the query.

## Related

- [`list_guides`](../list-guides) — Browse the Guide catalog level by level.
- [`get_guide`](../get-guide) — Load a Guide's full content by UUID.
- [`get_dive_guide`](/sql-reference/mcp/dives/get-dive-guide) — Entry point for Dive conventions.
- [`get_flight_guide`](/sql-reference/mcp/flights/get-flight-guide) — Entry point for Flight conventions.
- [Guides how-to](/key-tasks/guides/) — Step-by-step instructions for creating and managing Guides.

---

Source: https://motherduck.com/docs/sql-reference/mcp/guides/list-guides

# list_guides
> Browse your organization's Guides level by level, grouped by topic
Browse your organization's [Guides](/key-tasks/guides/) — markdown documents that capture metric definitions, join conventions, and domain context that AI agents need to query your data accurately.

## Description

The `list_guides` tool browses the Guide catalog with progressive disclosure. Called with no arguments, it lists the root level: Guides with no topic plus every topic with its Guide count. Pass `topic` to open one — you get the Guides stored exactly at that topic and the nested topics below it.

Guides are identified by UUID. Use [`get_guide`](../get-guide) with a `uuid` from the listing to read a Guide in full.

For query guidance and a full topic overview in one call, start with [`get_query_guide`](../get-query-guide) instead.

## Input parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `topic` | string | No | Open this topic — for example `"revenue-billing"` or `"core/metrics"` (no leading or trailing slash). Omit for the root level. |

## Output schema

```json
{
  "success": boolean,
  "topic": string,           // The level being listed ("" for root)
  "topics": [
    {
      "topic": string,       // Nested topic path
      "guide_count": number  // Number of guides in that subtree
    }
  ],
  "guides": [
    {
      "uuid": string,        // Guide UUID — use with get_guide
      "topic": string,       // The guide's topic ("" for guides without a topic)
      "title": string,       // Guide title
      "access": string,      // "user" or "organization"
      "description": string  // One-line summary
    }
  ],
  "error": string            // Error message (on failure)
}
```

## Example usage

**Browse the root level:**

```text
What guides does my organization have?
```

The AI assistant calls the tool with no arguments and receives the Guides without a topic plus the top-level topics.

**Open a topic:**

```text
Show me the guides about revenue and billing
```

```json
{
  "topic": "revenue-billing"
}
```

**Open a nested topic:**

```json
{
  "topic": "core/metrics"
}
```

## Success response example

```json
{
  "success": true,
  "topic": "revenue-billing",
  "topics": [
    {
      "topic": "revenue-billing/forecasting",
      "guide_count": 2
    }
  ],
  "guides": [
    {
      "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "topic": "revenue-billing",
      "title": "MRR and ARR Definitions",
      "access": "organization",
      "description": "How monthly and annual recurring revenue are calculated"
    },
    {
      "uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "topic": "revenue-billing",
      "title": "Billing Edge Cases",
      "access": "organization",
      "description": "Pitfalls when querying the billing tables"
    }
  ]
}
```

## Related

- [`get_query_guide`](../get-query-guide) — Entry point: query guidance plus a full topic overview.
- [`get_guide`](../get-guide) — Load a Guide's full content by UUID.
- [`create_guide`](../create-guide) — Create a new Guide.
- [Guides how-to](/key-tasks/guides/) — Step-by-step instructions for creating and managing Guides.

---

Source: https://motherduck.com/docs/sql-reference/mcp/guides/get-guide

# get_guide
> Load a Guide's full content by UUID, optionally pinning a historical version
Load a [Guide](/key-tasks/guides/) by UUID. Find a Guide's UUID with [`list_guides`](../list-guides) or through the entry points [`get_query_guide`](../get-query-guide), [`get_dive_guide`](/sql-reference/mcp/dives/get-dive-guide), and [`get_flight_guide`](/sql-reference/mcp/flights/get-flight-guide).

## Description

The `get_guide` tool returns a Guide's full markdown content plus its metadata and references. Guides are identified by UUID, consistent with Dives and Flights. Pass `version` to read a specific historical version; by default the current version is returned.

## Input parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `uuid` | string | Yes | The Guide's UUID, as returned by `list_guides` or a previous mutation. |
| `version` | integer | No | Version number to read. Defaults to the current version. |

## Output

On success, the tool returns the Guide as a plain-text document rather than a JSON object: the title, a metadata line (UUID, topic, version, access level), the description, the full markdown content, and a references footer. The response is mirrored into structured content as:

```json
{
  "text": string  // The rendered guide document
}
```

On failure, the tool returns a structured error:

```json
{
  "success": false,
  "error": string
}
```

## Example usage

**Read a Guide found through the topic overview:**

```text
How should I calculate MRR for our billing data?
```

The assistant calls [`get_query_guide`](../get-query-guide) or [`list_guides`](../list-guides) to find the relevant Guide's UUID, then loads it:

```json
{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```

**Read a specific historical version:**

```json
{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "version": 2
}
```

## Success response example

```text
MRR and ARR Definitions
uuid: a1b2c3d4-e5f6-7890-abcd-ef1234567890 · topic: revenue-billing · v3 · organization

How monthly and annual recurring revenue are calculated

# MRR and ARR Definitions

MRR is calculated as...

## References
- catalog md:billing main.subscriptions
```

## Related

- [`get_query_guide`](../get-query-guide) — Entry point: query guidance plus a topic overview.
- [`list_guides`](../list-guides) — Browse the Guide catalog to find a UUID.
- [`update_guide`](../update-guide) — Append a version to a 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.

---

Source: https://motherduck.com/docs/sql-reference/mcp/guides/create-guide

# 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.

---

Source: https://motherduck.com/docs/sql-reference/mcp/guides/update-guide

# update_guide
> Append a version to an existing Guide with updated content or references
Append a version to an existing [Guide](/key-tasks/guides/), identified by UUID. Use this to replace a Guide's full content. For smaller targeted edits, use [`edit_guide_content`](../edit-guide-content) instead.

## Description

The `update_guide` tool saves an updated version of an existing Guide. Omit `content` to carry the current text forward and only update metadata such as references. A supplied `references` list replaces the existing one — pass an empty array (`[]`) to clear all references, or omit `references` entirely to carry them forward.

To retitle or re-topic a Guide, use [`update_guide_metadata`](../update-guide-metadata). To change visibility, use [`set_guide_access`](../set-guide-access).

## Input parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `uuid` | string | Yes | The Guide's UUID, as returned by `list_guides` or a previous mutation. |
| `content` | string | No | New full markdown body. Omit to carry the current version's content forward. |
| `change_comment` | string | No | Optional note describing this version's change. |
| `external_id` | string | No | Optional caller-provided ID for this version (for example a git SHA). |
| `references` | array | No | Replaces the Guide's references. Pass `[]` to clear; omit to carry forward. See [reference object shape](/sql-reference/mcp/guides/create-guide#reference-object-shape). |

## Output schema

```json
{
  "success": boolean,
  "guide": {
    "id": string,
    "topic": string,
    "title": string,
    "description": string,
    "access": string,
    "current_version": number,
    "created_at": string,
    "updated_at": string,
    "version_change_comment": string,
    "version_external_id": string,
    "version_created_at": string,
    "references": array
  },
  "error": string
}
```

## Example usage

**Update the full content of a Guide:**

```text
Update the MRR guide to clarify that trial subscriptions are excluded
```

```json
{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "content": "# MRR and ARR Definitions\n\n...(updated content)...",
  "change_comment": "Clarify trial subscription exclusion logic"
}
```

**Add references without changing content:**

```json
{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "references": [
    {
      "type": "catalog",
      "url": "md:billing",
      "schema": "main",
      "table": "subscriptions"
    },
    {
      "type": "catalog",
      "url": "md:billing",
      "schema": "main",
      "table": "invoices"
    }
  ]
}
```

**Clear all references:**

```json
{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "references": []
}
```

## Related

- [`edit_guide_content`](../edit-guide-content) — Make targeted in-place edits without replacing the full content.
- [`update_guide_metadata`](../update-guide-metadata) — Retitle, re-topic, or update the description.
- [`get_guide`](../get-guide) — Read the current Guide content before updating.
- [Guides how-to](/key-tasks/guides/) — Step-by-step instructions for creating and managing Guides.

---

Source: https://motherduck.com/docs/sql-reference/mcp/guides/edit-guide-content

# edit_guide_content
> Apply targeted string replacements to a Guide and save the result as a versioned update
Apply one or more string replacements to a [Guide](/key-tasks/guides/), identified by UUID, and save the result as an updated version. No prior [`get_guide`](../get-guide) call is needed.

## Description

The `edit_guide_content` tool reads the stored Guide, applies the supplied edits in sequence, and persists the result as a version update. This is the right choice for small, targeted changes such as fixing a typo, updating a table name, or adding a section. For replacing the entire content, use [`update_guide`](../update-guide).

Each edit must supply an `old_string` that is unique in the current content (unless `replace_all` is set), and a different `new_string`. Edits apply in order — the output of one edit is the input for the next.

## Input parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `uuid` | string | Yes | The Guide's UUID, as returned by `list_guides` or a previous mutation. |
| `edits` | array | Yes | List of edits to apply in sequence. At least one edit is required. |
| `change_comment` | string | No | Optional note describing this version's change. |
| `external_id` | string | No | Optional caller-provided ID for this version (for example a git SHA). |

### Edit object shape

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `old_string` | string | Yes | The exact text to find. Must be unique in the content unless `replace_all` is true. |
| `new_string` | string | Yes | The replacement text. Must differ from `old_string`. |
| `replace_all` | boolean | No | Replace all occurrences of `old_string`. Defaults to `false`. |

## Output schema

```json
{
  "success": boolean,
  "guide": {
    "id": string,
    "topic": string,
    "title": string,
    "description": string,
    "access": string,
    "current_version": number,
    "created_at": string,
    "updated_at": string,
    "version_change_comment": string,
    "version_external_id": string,
    "version_created_at": string,
    "references": array
  },
  "edits_applied": number,       // Number of edits applied
  "total_replacements": number,  // Total string replacements made
  "error": string,               // Error message (on failure)
  "hint": string                 // Hint when old_string was not found (on failure)
}
```

## Example usage

**Fix a table name across a Guide:**

```text
Rename the orders table to customer_orders in the billing guide
```

```json
{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "edits": [
    {
      "old_string": "billing.main.orders",
      "new_string": "billing.main.customer_orders",
      "replace_all": true
    }
  ],
  "change_comment": "Rename orders to customer_orders after table migration"
}
```

**Apply multiple edits in one call:**

```json
{
  "uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "edits": [
    {
      "old_string": "updated_at < CURRENT_TIMESTAMP - INTERVAL '24 hours'",
      "new_string": "updated_at < CURRENT_TIMESTAMP - INTERVAL '12 hours'"
    },
    {
      "old_string": "daily freshness threshold",
      "new_string": "12-hour freshness threshold"
    }
  ],
  "change_comment": "Tighten freshness SLA from 24h to 12h"
}
```

## 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": 4,
    "created_at": "2025-06-01T10:00:00Z",
    "updated_at": "2025-07-01T14:22:00Z",
    "version_change_comment": "Rename orders to customer_orders after table migration",
    "version_external_id": null,
    "version_created_at": "2025-07-01T14:22:00Z",
    "references": []
  },
  "edits_applied": 1,
  "total_replacements": 3
}
```

## Error response example

```json
{
  "success": false,
  "error": "old_string not found in guide content",
  "edits_applied": 0,
  "hint": "The string 'billing.main.orders' was not found. Check that the text matches exactly, including whitespace."
}
```

## Related

- [`update_guide`](../update-guide) — Replace the full content in one call.
- [`get_guide`](../get-guide) — Read the current content to identify the text to replace.
- [Guides how-to](/key-tasks/guides/) — Step-by-step instructions for creating and managing Guides.

---

Source: https://motherduck.com/docs/sql-reference/mcp/guides/update-guide-metadata

# update_guide_metadata
> Change a Guide's title, description, or topic without creating a content version
Change a [Guide](/key-tasks/guides/)'s title, description, or topic without appending a content version. The Guide keeps its UUID and full version history.

## Description

The `update_guide_metadata` tool lets you retitle or re-topic a Guide without touching its content. Use it when a Guide's title or grouping is outdated — for example after a team reorganization or a product rename.

Provide at least one of `title`, `description`, or `topic`.

To update content, use [`update_guide`](../update-guide) or [`edit_guide_content`](../edit-guide-content) instead.

## Input parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `uuid` | string | Yes | The Guide's UUID, as returned by `list_guides` or a previous mutation. |
| `title` | string | No | New human-readable title. Must not be empty when supplied. |
| `description` | string | No | New one-line summary. Pass an empty string (`""`) to clear it. |
| `topic` | string | No | New grouping label — for example `"revenue-billing"` or `"core/metrics"` (no leading or trailing slash). Pass an empty string (`""`) to remove the topic. |

## Output schema

```json
{
  "success": boolean,
  "guide": {
    "id": string,
    "topic": string,           // Updated topic (null when cleared)
    "title": string,           // Updated title
    "description": string,     // Updated description
    "access": string,
    "current_version": number,
    "created_at": string,
    "updated_at": string
  },
  "error": string
}
```

## Example usage

**Move a Guide to a different topic:**

```text
Move the order filters guide from order-management to customer-orders
```

```json
{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "topic": "customer-orders",
  "title": "Customer Order Filters"
}
```

**Update only the description:**

```json
{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "description": "MRR and ARR definitions, including expansion and churn adjustments"
}
```

**Remove the topic (move the Guide to the root level):**

```json
{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "topic": ""
}
```

## Related

- [`update_guide`](../update-guide) — Append a content version.
- [`edit_guide_content`](../edit-guide-content) — Make targeted in-place content edits.
- [`set_guide_access`](../set-guide-access) — Change a Guide's visibility.
- [Guides how-to](/key-tasks/guides/) — Step-by-step instructions for creating and managing Guides.

---

Source: https://motherduck.com/docs/sql-reference/mcp/guides/set-guide-access

# set_guide_access
> Change a Guide's visibility between private and org-wide
Change a [Guide](/key-tasks/guides/)'s visibility to `"user"` (private) or `"organization"` (visible to your whole org). Setting org-wide access is admin-permission gated.

## Description

The `set_guide_access` tool controls who can see and read a Guide:

- **`"user"`** — private to the Guide's owner. Only you can read or modify it.
- **`"organization"`** — visible to everyone in your MotherDuck organization. Setting this level requires admin permission.

Use this tool to promote a personal Guide to org-wide after review, or to make a Guide private again. Access is the only visibility mechanism — a Guide's topic has no effect on who can see it.

## Input parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `uuid` | string | Yes | The Guide's UUID, as returned by `list_guides` or a previous mutation. |
| `access` | string | Yes | `"user"` (private) or `"organization"` (org-wide, admin-permission gated). |

## Output schema

```json
{
  "success": boolean,
  "guide": {
    "id": string,
    "topic": string,
    "title": string,
    "description": string,
    "access": string,       // Updated access level
    "current_version": number,
    "created_at": string,
    "updated_at": string
  },
  "error": string
}
```

## Example usage

**Publish a Guide to the whole org:**

```text
Make the MRR definitions guide available to the whole organization
```

```json
{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "access": "organization"
}
```

**Make a Guide private again:**

```json
{
  "uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "access": "user"
}
```

## Related

- [`create_guide`](../create-guide) — Set access at creation time.
- [`update_guide_metadata`](../update-guide-metadata) — Change title, description, or topic.
- [Guides how-to](/key-tasks/guides/) — Step-by-step instructions for creating and managing Guides.

---

Source: https://motherduck.com/docs/sql-reference/mcp/guides/delete-guide

# delete_guide
> Soft-delete a Guide while preserving its version history
Soft-delete a [Guide](/key-tasks/guides/), identified by UUID. The version history is preserved for audit purposes.

## Description

The `delete_guide` tool removes a Guide from the active catalog. The Guide's version history is retained internally but is not exposed through normal tools after deletion. Only the Guide's owner can delete it.

References from other Guides to a deleted Guide are left dangling and resolve to not-found — clean them up in the referencing Guides if needed.

There is no undo through the MCP tools — if you delete a Guide by mistake, contact MotherDuck support.

:::warning
Deleting an org-wide Guide removes it from all users' Guide catalogs immediately. Verify you have the right Guide (read it with [`get_guide`](../get-guide)) before confirming deletion.
:::

## Input parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `uuid` | string | Yes | The Guide's UUID, as returned by `list_guides` or a previous mutation. |

## Output schema

```json
{
  "success": boolean,
  "deleted": boolean,  // true when the guide was successfully deleted
  "error": string      // Error message (on failure)
}
```

## Example usage

**Delete a Guide:**

```text
Delete the outdated order-management guide
```

The assistant finds the Guide's UUID with [`list_guides`](../list-guides), verifies it's the right one, and calls:

```json
{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```

## Success response example

```json
{
  "success": true,
  "deleted": true
}
```

## Related

- [`list_guides`](../list-guides) — Find the Guide's UUID before deleting.
- [`get_guide`](../get-guide) — Verify the Guide content before deleting.
- [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%2F&page_title=MotherDuck%20Documentation%20-%20Guides&text=<url-encoded user feedback, max 2000 characters>
```

Optionally append `&source=<url-encoded interface identifier>` such as `claude.ai` or `chatgpt`.

`page_path` and `text` are required; `page_title` and `source` are optional. Responses: `200 {"feedback_id": "<uuid>"}`, `400` for malformed query parameters, and `429` when rate-limited.