list_guides

Preview

This feature is in preview and is subject to change.

Browse your organization's 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 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 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

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

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:

Show me the guides about revenue and billing

{
  "topic": "revenue-billing"
}

Open a nested topic:

{
  "topic": "core/metrics"
}

Success response example

{
  "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 — Entry point: query guidance plus a full topic overview.
• get_guide — Load a guide's full content by UUID.
• create_guide — Create a new guide.
• Guides how-to — Step-by-step instructions for creating and managing Guides.