# Guides functions
> SQL table functions for creating, reading, updating, and deleting MotherDuck Guides.
SQL table functions for managing [Guides](/key-tasks/guides/) — markdown documents that capture metric definitions, join conventions, and domain context that AI agents use to answer your organization's data questions correctly.

Guides are identified by UUID, consistent with Dives and Flights. An optional `topic` — a slash-separated grouping label like `revenue-billing` or `core/metrics` — groups related guides for browsing and filtering. Topics carry no uniqueness: multiple guides can share a topic.

:::note
These functions run server-side on MotherDuck. They are not available on local-only DuckDB connections.
:::

Use Guides through the [MotherDuck MCP server](/sql-reference/mcp/) to let AI assistants read and write them automatically, or run the SQL functions directly from any MotherDuck connection.

```sql
-- List all guides visible to you
SELECT * FROM MD_LIST_GUIDES();

-- Read a guide by id
SELECT title, content FROM MD_GET_GUIDE(id = '<guide_uuid>');

-- Create a guide
SELECT id, topic, title, current_version
FROM MD_CREATE_GUIDE(
  topic = 'revenue-billing',
  title = 'MRR and ARR Definitions',
  content = '# MRR and ARR Definitions ...',
  access = 'organization'
);
```

## Available functions

## Included pages

- [MD_LIST_GUIDES](https://motherduck.com/docs/sql-reference/motherduck-sql-reference/guides/md-list-guides): List Guides visible to you, filtered by topic subtree or reference
- [MD_GET_GUIDE](https://motherduck.com/docs/sql-reference/motherduck-sql-reference/guides/md-get-guide): Read a Guide's full content by id, optionally at a historical version
- [MD_CREATE_GUIDE](https://motherduck.com/docs/sql-reference/motherduck-sql-reference/guides/md-create-guide): Create a new Guide — a markdown document capturing org-specific context for AI agents
- [MD_UPDATE_GUIDE](https://motherduck.com/docs/sql-reference/motherduck-sql-reference/guides/md-update-guide): Append a version to an existing Guide with updated content or references
- [MD_UPDATE_GUIDE_METADATA](https://motherduck.com/docs/sql-reference/motherduck-sql-reference/guides/md-update-guide-metadata): Retitle or re-topic a Guide, or update its description, without creating a content version
- [MD_SET_GUIDE_ACCESS](https://motherduck.com/docs/sql-reference/motherduck-sql-reference/guides/md-set-guide-access): Change a Guide's visibility between private and org-wide
- [MD_LIST_GUIDE_VERSIONS](https://motherduck.com/docs/sql-reference/motherduck-sql-reference/guides/md-list-guide-versions): List a Guide's version history without content
- [MD_DELETE_GUIDE](https://motherduck.com/docs/sql-reference/motherduck-sql-reference/guides/md-delete-guide): Soft-delete a Guide while preserving its version history


---

## 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%2Fmotherduck-sql-reference%2Fguides%2F&page_title=Guides%20functions&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.