Building a Data Stack Live with AI AgentsLivestream August 18

Skip to main content

create_guide

Preview
This feature is in preview and is subject to change.

Create a new Guide — 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 and 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 and search_catalog surface related guides automatically.

Input parameters​

ParameterTypeRequiredDescription
titlestringYesHuman-readable title. Must not be empty.
contentstringYesFull markdown body of the guide. Maximum 1 MB.
topicstringNoSlash-separated grouping label — for example "revenue-billing" or "core/metrics" (no leading or trailing slash). Omit for no topic.
descriptionstringNoShort one-line summary shown in the guide index.
accessstringNo"user" (private, default) or "organization" (org-wide, admin-permission gated).
change_commentstringNoOptional note describing this initial version.
external_idstringNoOptional caller-provided ID for this version (for example a git SHA).
referencesarrayNoStructured references to the 1–5 objects this guide explains. See reference object shape.

Reference object shape​

FieldTypeRequiredDescription
typestringYesOne of "catalog", "dive", "flight", or "guide"
urlstringConditionalMotherDuck URL — required for catalog type (for example "md:my_database" or a "md:_share/..." URL)
schemastringConditionalSchema name — required when table, view, or macro is set
tablestringNoTable name (catalog only)
columnstringNoColumn name (catalog only, requires table)
viewstringNoView name (catalog only, mutually exclusive with table/macro)
macrostringNoMacro name (catalog only, mutually exclusive with table/view)
uuidstringConditionalUUID of the referenced Dive, Flight, or Guide
descriptionstringNoWhy this reference exists

Output schema​

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

Create a guide explaining how we calculate MRR for the billing team
{
  "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:

Remember that I prefer dark-themed Dives with the watermelon accent color
{
  "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​

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