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


---

## 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%2Fupdate-guide%2F&page_title=update_guide&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.