edit_guide_content

Preview

This feature is in preview and is subject to change.

Apply one or more string replacements to a Guide, identified by UUID, and save the result as an updated version. No prior 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.

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

{
  "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:

Rename the orders table to customer_orders in the billing guide

{
  "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:

{
  "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

{
  "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

{
  "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 — Replace the full content in one call.
• get_guide — Read the current content to identify the text to replace.
• Guides how-to — Step-by-step instructions for creating and managing Guides.