# Content tools

These are the MCP tools your agent uses to read and write articles. You rarely call them by name: you describe what you want, and your agent picks the right tool. Knowing what exists helps you phrase requests and understand what happened.

For connection setup, see [MCP server overview and authentication](/articles/mcp-overview). For sections and collections, see [Structure tools](/articles/mcp-structure-tools).

## At a glance

| Tool | What it does |
| --- | --- |
| `list_projects` | Lists projects you have access to |
| `list_articles` | Lists articles, with filters and search |
| `get_article` | Fetches one article in full |
| `create_article` | Creates an article, draft by default |
| `update_article` | Edits an article's draft |
| `publish_article` | Makes an article live |
| `unpublish_article` | Takes an article off the live site |
| `delete_article` | Permanently deletes an article |
| `get_image_upload_url` | Gets an upload URL for an image |
| `get_directives` | Lists supported markdown directives |

## Reading

### list_projects

Returns every project your account can access, with each project's name, subdomain, and id. Agents usually call this first to find the right project.

### list_articles

Lists articles in a project. Supports filtering by collection, by section, by status (`draft` or `published`), and text search across titles and content. Returns at most 50 results, so agents narrow with filters on large projects.

### get_article

Fetches everything about one article: title, status, collection, full markdown content, meta description, live and preview URLs, any content warnings, and the article's heading anchors. Anchors matter for cross-linking: your agent can link straight to a section of another article with `url#anchor` instead of guessing.

## Writing

### create_article

Creates an article in a collection. Articles start as drafts unless the agent passes `status: "published"` explicitly. Optional extras: a custom URL slug and a meta description for search engines. When an article is published, the response includes the live URL so your agent can hand it straight back to you.

### update_article

Edits title, content, slug, or meta description, or moves the article to a different collection. Edits always land on the article's draft. If the article is already live, the published version stays untouched until the next publish. See [How authoring works](/articles/how-authoring-works) for the draft model.

### publish_article and unpublish_article

`publish_article` promotes the draft to the live site and returns the public URL. `unpublish_article` removes the article from the live site while preserving the content as a draft, ready to republish later.

### delete_article

Permanently deletes an article and its history. There is no undo.

:::callout{type="warning"}
Deletion is immediate and irreversible. If you might want the article back, ask your agent to unpublish it instead.
:::

## Images

### get_image_upload_url

Hands the agent a short-lived upload URL plus the final public URL of the image. The agent uploads your screenshot or diagram, then references it in markdown as `![alt text](url)`. Accepted formats are PNG, JPEG, GIF, and WebP, up to 10 MB. The upload URL expires after 5 minutes, so agents request one right before uploading. More in [Add images and captions](/articles/images-and-captions).

## Discovering formatting

### get_directives

Returns the full registry of markdown directives the docs site can render: callouts, tabs, accordions, video embeds, and alignment, with every attribute and allowed value. Agents call this to write valid rich content without guessing. The human-readable version is the [Directives reference](/articles/directives-reference).

## Prompts to try

```
Find every article that mentions "webhooks" and update them to use the new endpoint name.
```

```
Draft an article about our refund policy in the Billing collection, but do not publish it yet.
```

```
Take the screenshot at ~/Desktop/settings.png, upload it, and add it to the article about project settings.
```