# Tools

<!-- Generated by scripts/gen-reference.mjs from src/data/catalog.json. Do not edit by hand. -->

Each action has two names: the dotted one for the REST API (`posts.create`) and the MCP tool name
(`posts_create`). Both take the same JSON input.

- **Read-only** actions change nothing. MCP clients see `readOnlyHint: true`.
- **Needs approval** actions never run from MCP or the REST API. MCP turns them into an approval card
  in the app; the REST API answers `403` with `ApprovalRequired`. See [Approvals](/concepts/approvals/).

| Action | MCP tool | Kind |
|---|---|---|
| [`accounts.list`](#accountslist) | `accounts_list` | Read-only |
| [`providers.limits`](#providerslimits) | `providers_limits` | Read-only |
| [`posts.list`](#postslist) | `posts_list` | Read-only |
| [`posts.get`](#postsget) | `posts_get` | Read-only |
| [`posts.create`](#postscreate) | `posts_create` | Write |
| [`posts.update`](#postsupdate) | `posts_update` | Write |
| [`posts.setVersionText`](#postssetversiontext) | `posts_setVersionText` | Write |
| [`posts.setOption`](#postssetoption) | `posts_setOption` | Write |
| [`posts.validate`](#postsvalidate) | `posts_validate` | Read-only |
| [`posts.schedule`](#postsschedule) | `posts_schedule` | Needs approval |
| [`posts.publishNow`](#postspublishnow) | `posts_publishNow` | Needs approval |
| [`posts.delete`](#postsdelete) | `posts_delete` | Needs approval |
| [`providers.list`](#providerslist) | `providers_list` | Read-only |
| [`accounts.delete`](#accountsdelete) | `accounts_delete` | Needs approval |
| [`media.list`](#medialist) | `media_list` | Read-only |
| [`posts.metrics`](#postsmetrics) | `posts_metrics` | Read-only |
| [`analytics.summary`](#analyticssummary) | `analytics_summary` | Read-only |
| [`ui.getContext`](#uigetcontext) | `ui_getContext` | Read-only |

## accounts.list

List connected social accounts.

- MCP tool: `accounts_list`
- REST: `POST /api/agent/tools/accounts.list`
- Kind: read-only

No input. Send `{}`.

## providers.limits

Character, media and thread limits of every provider. Respect them when writing posts.

- MCP tool: `providers_limits`
- REST: `POST /api/agent/tools/providers.limits`
- Kind: read-only

No input. Send `{}`.

## posts.list

List posts, newest first.

- MCP tool: `posts_list`
- REST: `POST /api/agent/tools/posts.list`
- Kind: read-only

| Field | Type | Required | Description |
|---|---|---|---|
| `status` | `"Draft"` \| `"Scheduled"` \| `"Publishing"` \| `"Published"` \| `"Failed"` |  |  |

Minimal input:

```json
{}
```

## posts.get

Get one post with all its versions.

- MCP tool: `posts_get`
- REST: `POST /api/agent/tools/posts.get`
- Kind: read-only

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |

Minimal input:

```json
{"id":"…"}
```

## posts.create

Create a draft post. Passing scheduledAt from the agent still needs approval via posts.schedule.

- MCP tool: `posts_create`
- REST: `POST /api/agent/tools/posts.create`
- Kind: write, runs directly

| Field | Type | Required | Description |
|---|---|---|---|
| `accountIds` | string[] |  | Default: `[]`. |
| `body` | string |  | Text of the original version. Default: `""`. |
| `scheduledAt` | string |  | ISO-8601 instant. Empty = save as draft. |

Minimal input:

```json
{}
```

## posts.update

Replace accounts, versions and time of an editable post. On a scheduled post it needs the user's approval.

- MCP tool: `posts_update`
- REST: `POST /api/agent/tools/posts.update`
- Kind: write, runs directly

| Field | Type | Required | Description |
|---|---|---|---|
| `scheduledAt` | string |  |  |
| `baseUpdatedAt` | string |  | The post's updatedAt this change is based on. When set and the post changed since, nothing is saved (Conflict). |
| `versions` | object[] | yes |  |
| `versions[].accountId` | string |  | Account this version overrides, or empty for the original version. |
| `versions[].content` | object[] | yes |  |
| `versions[].content[].body` | string | yes | Plain text body. No HTML. |
| `versions[].content[].media` | string[] |  | Media ids from the media library, in display order. Default: `[]`. |
| `versions[].options` | object |  | Network options of this account's version, by key (see providers.limits): a YouTube title, TikTok privacy, a Pinterest board. Default: `{}`. |
| `id` | string | yes |  |
| `accountIds` | string[] | yes |  |

Minimal input:

```json
{"versions":[],"id":"…","accountIds":[]}
```

## posts.setVersionText

Rewrite the text of one version of a post (original or a specific account). On a scheduled post it needs the user's approval.

- MCP tool: `posts_setVersionText`
- REST: `POST /api/agent/tools/posts.setVersionText`
- Kind: write, runs directly

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `accountId` | string |  | Account whose version to edit. Empty = the original version. Editing an account that has no override creates one from the original. |
| `body` | string | yes |  |
| `itemIndex` | integer |  | Default: `0`. |

Minimal input:

```json
{"id":"…","body":"…"}
```

## posts.setOption

Set a network option of a post (a YouTube title, TikTok privacy, a Pinterest board). Keys and choices are in providers.limits. On a scheduled post it needs the user's approval.

- MCP tool: `posts_setOption`
- REST: `POST /api/agent/tools/posts.setOption`
- Kind: write, runs directly

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `accountId` | string |  | Account whose version to set it on. Empty = the original version, which applies to every account of the network. |
| `key` | string | yes | The option's key from providers.limits, e.g. youtube.title, tiktok.privacy, pinterest.board. |
| `value` | string |  | The value; empty removes it (the default applies). |

Minimal input:

```json
{"id":"…","key":"…"}
```

## posts.validate

Check a post against every selected provider's limits.

- MCP tool: `posts_validate`
- REST: `POST /api/agent/tools/posts.validate`
- Kind: read-only

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |

Minimal input:

```json
{"id":"…"}
```

## posts.schedule

Schedule a post for publishing. Public and irreversible once published.

- MCP tool: `posts_schedule`
- REST: `POST /api/agent/tools/posts.schedule`
- Kind: needs approval

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |
| `at` | string | yes | ISO-8601 instant in the future. |

Minimal input:

```json
{"id":"…","at":"…"}
```

## posts.publishNow

Publish a post immediately to all its accounts. Public and irreversible.

- MCP tool: `posts_publishNow`
- REST: `POST /api/agent/tools/posts.publishNow`
- Kind: needs approval

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |

Minimal input:

```json
{"id":"…"}
```

## posts.delete

Delete a post that is not published.

- MCP tool: `posts_delete`
- REST: `POST /api/agent/tools/posts.delete`
- Kind: needs approval

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |

Minimal input:

```json
{"id":"…"}
```

## providers.list

Providers this server can connect to. Connecting needs the user's browser (OAuth); give them connectUrl.

- MCP tool: `providers_list`
- REST: `POST /api/agent/tools/providers.list`
- Kind: read-only

No input. Send `{}`.

## accounts.delete

Disconnect an account. Its scheduled posts will fail for that account.

- MCP tool: `accounts_delete`
- REST: `POST /api/agent/tools/accounts.delete`
- Kind: needs approval

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |

Minimal input:

```json
{"id":"…"}
```

## media.list

The user's image library. Put media ids into a content item's media list to attach images to a post.

- MCP tool: `media_list`
- REST: `POST /api/agent/tools/media.list`
- Kind: read-only

No input. Send `{}`.

## posts.metrics

Statistics of a published post, per account: views, likes, comments, shares and what else each network reports (providers.limits lists them). Read about an hour after publishing, then at 6 h, 24 h, 3, 7 and 30 days.

- MCP tool: `posts_metrics`
- REST: `POST /api/agent/tools/posts.metrics`
- Kind: read-only

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | string | yes |  |

Minimal input:

```json
{"id":"…"}
```

## analytics.summary

How published posts did in a time range: totals per account and per network, the 10 posts with the most engagement (likes, comments, shares, quotes, saves), and bestTimes: engagement per weekday and hour in timeZone, with the number of posts behind each (lowConfidence under 3 posts).

- MCP tool: `analytics_summary`
- REST: `POST /api/agent/tools/analytics.summary`
- Kind: read-only

| Field | Type | Required | Description |
|---|---|---|---|
| `from` | string | yes | ISO-8601 instant, start of the range (inclusive), e.g. 2026-09-01T00:00:00Z. |
| `to` | string | yes | ISO-8601 instant, end of the range (exclusive). At most 400 days after from. |
| `accountIds` | string[] |  | Only posts published to these accounts. Empty = every account. Default: `[]`. |
| `timeZone` | string |  | IANA time zone for bestTimes, e.g. Europe/Paris: the user's. Unknown names count as UTC. Default: `"UTC"`. |

Minimal input:

```json
{"from":"…","to":"…"}
```

## ui.getContext

What the user is looking at: page, open post and version tab. Use it to resolve 'this post' or 'this version'.

- MCP tool: `ui_getContext`
- REST: `POST /api/agent/tools/ui.getContext`
- Kind: read-only

No input. Send `{}`.