# list_guides
> Browse your organization's Guides level by level, grouped by topic
Browse your organization's [Guides](/key-tasks/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`](../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`](../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

```json
{
  "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:**

```text
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:**

```text
Show me the guides about revenue and billing
```

```json
{
  "topic": "revenue-billing"
}
```

**Open a nested topic:**

```json
{
  "topic": "core/metrics"
}
```

## Success response example

```json
{
  "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`](../get-query-guide) — Entry point: query guidance plus a full topic overview.
- [`get_guide`](../get-guide) — Load a guide's full content by UUID.
- [`create_guide`](../create-guide) — Create a new guide.
- [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%2Flist-guides%2F&page_title=list_guides&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.