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


---

## 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%2Fedit-guide-content%2F&page_title=edit_guide_content&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.