> ## Documentation Index
> Fetch the complete documentation index at: https://docs.postbreeze.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools

> The v1 MCP tool surface — what Claude / Cursor can do on your behalf.

Every tool is **workspace-scoped**: the API key fixes which workspace
the LLM can read or write to. **No tool takes a `workspaceId`
argument** — the workspace is inferred from the bearer key, so the
model never has to look it up first. Destructive tools are flagged
so MCP clients can prompt before invoking them.

## Read-only

### `list_workspaces`

Returns the workspace this API key is bound to. Useful for the LLM
to surface the brand/account name (e.g. *"Acme Co."*) before
scheduling. Normally a single-entry list.

### `list_posts`

Returns the workspace's posts, newest first, with caption, scheduled
time, target platforms, and lifecycle status (DRAFT / SCHEDULED /
PUBLISHED / PARTIALLY\_PUBLISHED / FAILED).

### `get_post`

Returns a single post with its caption, scheduled time, per-platform
targets, publish errors, and attached media.

### `list_connected_accounts`

Returns every social account connected to the workspace — platform,
`@handle`, and connection status. These are the IDs you pass to
`schedule_post` as `platforms[].accountId`.

### `list_media`

Lists items in the workspace's media library. Use `id` values as the
`mediaIds` array when scheduling a post with pre-uploaded
attachments.

### `list_comments`

Returns inbox comments across every connected platform (Instagram, X,
YouTube, Facebook). Supports a `platform` filter and `unreadOnly`
flag. Reads from cache — call `refresh_comments` first if the user
expects very-recent activity.

### `get_analytics_overview`

Returns workspace-wide KPIs (impressions, engagement, follower
growth) plus a per-platform breakdown and a bucketed engagement
trend series. Each KPI includes `percentageChange` vs the prior
equal-length window (null when no prior data exists — the LLM is
instructed not to fabricate a delta in that case).

### `get_top_posts`

Returns the workspace's published posts within the range, sorted by
summed engagement. Includes caption preview, thumbnail URL,
platform, and per-post engagement components.

### `get_<platform>_analytics`

Per-platform analytics deep-dive: `get_instagram_analytics`,
`get_facebook_analytics`, `get_tiktok_analytics`,
`get_x_analytics`, `get_linkedin_analytics`,
`get_youtube_analytics`, `get_pinterest_analytics`,
`get_threads_analytics`. Each takes a `socialAccountId` from
`list_connected_accounts` plus a `range`. Returns the platform's
native shape (Pinterest pins, TikTok lifetime totals, etc.) so the
model can reason about each platform's native concepts.

## Writes

### `schedule_post`

Creates a post and (optionally) schedules it to publish. Uses the
flat shape (`content` + `platforms`).

**Required:** `platforms` — one entry per account to publish to.

**Optional:**

* `content` — default caption used for every platform unless
  overridden via `platforms[].captionOverride`.
* `scheduledFor` — ISO-8601 UTC publish time. Omit to save as a draft.
* `mediaItems` — attach media by URL; the server fetches the bytes
  (SSRF-guarded) before publish. Each entry is `{ type, url,
  altText? }`.
* `mediaIds` — IDs of media already in the library (from `list_media`
  or `ingest_media_from_url`).

**Per-platform overrides** on each `platforms[]` entry:

* `captionOverride` — replace `content` for this platform only.
* `firstComment` — text auto-posted as a reply right after publish
  (Instagram, Facebook, LinkedIn, X, YouTube, Threads).

### `update_post`

Edits a DRAFT or SCHEDULED post in place. Pass the fields you want to
change. Terminal statuses (PUBLISHING / PUBLISHED / FAILED) reject.

### `reschedule_post`

Moves a SCHEDULED post to a new publish time. Same retry policy as a
fresh schedule.

### `retry_post`

Re-runs the publish pipeline for a FAILED post. Use when the failure
was a transient network/provider error.

### `cancel_post` *(destructive)*

Cancels a scheduled post. MCP clients surface a confirmation prompt
because of the `destructiveHint` annotation. Audit history of any
prior publish attempts is retained.

### `ingest_media_from_url`

Fetches a public HTTPS URL server-side (SSRF-guarded) and stores the
bytes in the workspace's media library. Returns the new
`mediaAssetId`. Most callers don't need this — `schedule_post`
already accepts `mediaItems` URLs directly. Use it when you want to
attach the same asset to multiple posts without re-uploading.

### `refresh_comments`

Forces a live fetch of new comments from every connected platform.
Call before `list_comments` when the user expects very-recent
activity. Returns `{ newCount }`.

### `reply_to_comment`

Posts a reply to an inbox comment. Per-platform character limits: X
280, IG 2,200, YouTube 10,000. Text is sent verbatim — Markdown gets
stripped by the platform.

### `mark_comment_read`

Flips the inbox read state on a comment.

## Annotations reference

Postbreeze tools set the standard MCP annotations:

* `readOnlyHint: true` on every list / get
* `destructiveHint: true` on `cancel_post`
* `openWorldHint: false` everywhere — these tools only touch the
  Postbreeze workspace, never the wider internet

Your MCP client decides how to surface these (Claude Desktop, for
example, asks for confirmation before destructive tool calls).