# MD_CREATE_GUIDE
> Create a new Guide — a markdown document capturing org-specific context for AI agents
Create a new [Guide](/key-tasks/guides/), identified by a generated UUID. Returns the created guide's metadata and initial version information.

## Syntax

```sql
SELECT * FROM MD_CREATE_GUIDE(
  topic = 'revenue-billing',
  title = 'MRR and ARR Definitions',
  content = '# MRR and ARR Definitions ...',
  description = 'How MRR and ARR are calculated',
  access = 'organization'
);
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `title` | `VARCHAR` | Yes | Human-readable title. Must not be empty. |
| `content` | `VARCHAR` | Yes | Full markdown body of the guide. Maximum 1 MB. |
| `topic` | `VARCHAR` | No | Slash-separated grouping label — for example `'revenue-billing'` or `'core/metrics'`. No leading or trailing slash. Omit for no topic. |
| `description` | `VARCHAR` | No | Short one-line summary shown in `MD_LIST_GUIDES`. |
| `access` | `VARCHAR` | No | `'user'` (private, default) or `'organization'` (org-wide, admin-permission gated). |
| `change_comment` | `VARCHAR` | No | Note describing this initial version. |
| `external_id` | `VARCHAR` | No | Caller-provided ID for this version (for example a git SHA). |
| `"references"` | `STRUCT[]` | No | Structured references to the objects this guide explains. See [reference struct](/sql-reference/motherduck-sql-reference/guides/md-list-guides#reference-struct). |

Topics are grouping labels only — they carry no uniqueness, so multiple guides can share the same topic.

## Return columns

| Column | Type | Description |
|--------|------|-------------|
| `id` | `UUID` | Generated identifier of the created guide |
| `topic` | `VARCHAR` | Grouping label (`NULL` if omitted) |
| `title` | `VARCHAR` | Guide title |
| `description` | `VARCHAR` | One-line summary |
| `owner_id` | `UUID` | UUID of the guide owner |
| `owner_name` | `VARCHAR` | Name of the guide owner |
| `access` | `VARCHAR` | `'user'` or `'organization'` |
| `current_version` | `UINTEGER` | Version number (1 for newly created guides) |
| `created_at` | `TIMESTAMP WITH TIME ZONE` | When the guide was created |
| `updated_at` | `TIMESTAMP WITH TIME ZONE` | When the guide was last updated |
| `version_change_comment` | `VARCHAR` | Note for the initial version |
| `version_external_id` | `VARCHAR` | Caller-provided version ID |
| `version_created_at` | `TIMESTAMP WITH TIME ZONE` | When the initial version was created |
| `references` | `STRUCT[]` | Resolved references |

## Examples

Create an org-wide metric definition guide:

```sql
SELECT id, topic, current_version
FROM MD_CREATE_GUIDE(
  topic = 'revenue-billing',
  title = 'MRR and ARR Definitions',
  description = 'How monthly and annual recurring revenue are calculated',
  content = '# MRR and ARR Definitions

MRR is the sum of all active subscription amounts normalized to a monthly value.

Key rules:
- Use the subscriptions table, not invoices
- Filter to status = active
- Exclude trial subscriptions (trial_end IS NULL)',
  access = 'organization',
  change_comment = 'Initial version'
);
```

Create a private guide without a topic:

```sql
SELECT id, title
FROM MD_CREATE_GUIDE(
  title = 'My scratch notes',
  content = 'Always double-check the currency column.'
);
```

## Related

- [`MD_GET_GUIDE`](../md-get-guide) — Read a guide's content.
- [`MD_UPDATE_GUIDE`](../md-update-guide) — Append a content version.
- [`MD_DELETE_GUIDE`](../md-delete-guide) — Delete a guide.
- [`create_guide` MCP tool](/sql-reference/mcp/guides/create-guide) — AI assistant equivalent.


---

## 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%2Fmd-create-guide%2F&page_title=MD_CREATE_GUIDE&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.