# Tools

Source: https://docs.bearletter.com/mcp/tools

Each tool does one thing and runs as you, with the same checks, plans and limits as the dashboard. A tool that needs a permission the agent was not given asks for it.

Tools that read are marked read-only; tools that change something public are marked so agents can ask you first.

## Docs and blog

| Tool | Does | Permission |
| --- | --- | --- |
| `get_blog_guide` | Reads these docs: the index, or a page by its path. | none |
| `get_blog` | The blog's title, address, time zone and plan. | `read` |
| `update_blog_settings` | Language, time zone, visit counts, AI training, address. | `blog` |

## Blog files

The site files have fixed names; only files under `posts/`, `pages/` and `podcast/` are created, renamed or moved. See [The blog folder](/blog/folder).

| Tool | Does | Permission |
| --- | --- | --- |
| `list_blog_files` | Files in the folder; `kind` is `post`, `page`, `episode` or `site`. | `read` |
| `read_blog_file` | One file with its content, its unpublished changes and `writeSeq`. | `read` |
| `save_blog_file` | Creates or replaces a file as readers see it. | `write`; `blog` for site files |
| `move_blog_file` | Renames or moves a post, page or episode; a public post or page keeps its old address. | `write` |
| `delete_blog_file` | Deletes a file with its revisions. | `write`; `blog` for site files |

## Write

A draft is a post, page or episode with `publish: false`. Editing a published file keeps what readers see and stores the edit as unpublished changes until it is published.

| Tool | Does | Permission |
| --- | --- | --- |
| `create_draft` | A new private draft: a post, a page or a podcast episode. | `write` |
| `save_draft` | Saves a draft, or a published file's unpublished changes. | `write` |
| `preview_file` | A 30-minute link showing a file with its changes as it would look. | `read` |
| `publish_file` | Publishes a draft or a file's unpublished changes, now or at a time. | `write` |
| `unpublish_file` | Takes a published or scheduled file back to a draft. | `write` |
| `discard_changes` | Drops a published file's unpublished changes. | `write` |

## Look

| Tool | Does | Permission |
| --- | --- | --- |
| `list_themes` | The built-in themes and the current appearance. | `read` |
| `preview_styles` | A 30-minute link showing the blog with a theme or a new stylesheet. | `read` |
| `apply_theme` | Replaces `styles.css` with a built-in theme. | `blog` |
| `set_appearance` | Accent color, text width, font, size. | `blog` |

## Media

Files never pass through the tools: they are downloaded from their public address and uploaded straight to storage.

| Tool | Does | Permission |
| --- | --- | --- |
| `list_media` | Files with their public address and how often they are used. | `read` |
| `start_media_upload` | Reserves a file and returns an address to upload it to with HTTP PUT. | `media` |
| `finish_media_upload` | Checks the uploaded file and adds it to the library. | `media` |

## Subscribers and stats

| Tool | Does | Permission |
| --- | --- | --- |
| `list_subscribers` | Subscribers and counts, 50 at a time. | `subscribers` |
| `export_subscribers` | The list as CSV. | `subscribers` |
| `add_subscriber` | Adds one address, as you would by hand. | `subscribers` |
| `get_blog_stats` | Visits by day, top posts and referrers. | `read` |

## How tools behave

- Read before you write: every change passes back the `writeSeq` that was read. If the file changed since, the change is refused; read it again.
- A refused save says which lines to fix, in the same words as the dashboard.
- Preview, then apply: `preview_styles` and `preview_file` give you a link to look at first.
- Results are JSON text.
