# MCP tools

Every tool the server offers, what it needs, and which ones spend credits.


An assistant only sees the tools its permissions allow. Read-only tools never change anything; tools marked destructive delete data and say so to the assistant.

| Tool | What it does | Needs scope | Notes |
|---|---|---|---|
| `list_social_accounts` | Lists the social accounts the user has connected, with whether each needs reconnecting. Call this first: the platform names it returns are what create_post accepts. | `accounts:read` | read-only |
| `list_posts` | Lists posts by status (draft, scheduled, published, failed), newest scheduled first. Optionally filter by tag. | `posts:read` | read-only |
| `get_post` | Returns one post with the per-platform result: status, link to the live post, and a plain-language error when it failed. | `posts:read` | read-only |
| `create_post` | Creates a post. With scheduled_at it is scheduled to every listed platform (using the most recently connected account of each); without it, it is saved as a draft the user can review in the dashboard. Does not publish immediately. Call list_social_accounts first. Pass idempotency_key when retrying. | `posts:write` | - |
| `update_post` | Changes the caption, title, tags or time of a draft or a scheduled post. Giving a draft a scheduled_at schedules it. Published posts cannot be edited. | `posts:write` | - |
| `delete_post` | Permanently deletes a draft or a scheduled post that has not started publishing. Cannot be undone. Published posts must be deleted on the platform. | `posts:write` | destructive |
| `upload_media_from_url` | Downloads a public https image or short video (up to 25 MB) into the media library and returns a media_id to use in create_post. | `media:write` | - |
| `shorten_links` | Replaces every http(s) link in the text with a creatorhyve.com short link that counts clicks, and returns the new text. | `links:manage` | - |
| `list_templates` | Lists the saved templates and signatures (reusable text such as a hashtag block or a closing line) so they can be reused in posts. | `posts:read` | read-only |
| `save_template` | Saves reusable text as a template, or as a signature (text appended to the end of posts). Up to 50 per user. | `posts:write` | - |
| `get_usage` | Returns the plan, credit balance, how many posts can still be scheduled this month, and how many credits assistants may still spend today. | `posts:read` | read-only |
| `get_analytics` | Totals (views, likes, comments), a per-platform breakdown and the top posts for the last N days. Metrics are collected once a day. | `analytics:read` | read-only |
| `get_brand_kit` | Returns the user's brand voice, tone, keywords, content pillars and target audience. Use it to write posts in their voice. | `posts:read` | read-only |
| `generate_image` | Generates one AI image and saves it to the media library. Spends credits (see get_usage). Returns a media_id usable in create_post. | `media:write` | spends credits |
| `list_autoflows` | Lists the 10 most recent AutoFlows (campaigns that generate and schedule posts) with their status. | `posts:read` | read-only |
| `launch_autoflow` | Creates an AutoFlow that writes and schedules posts for a goal. Spends credits: call once with confirm=false to see the cost, then again with confirm=true. Default mode is "review" (posts wait for the user to approve them). | `posts:write` | spends credits |

## Suggested flow for an assistant

1. `list_social_accounts` to see which platforms are connected.
2. `get_brand_kit` to write in the user's voice.
3. `create_post` without `scheduled_at` to save a draft, or with it to schedule.
4. `get_post` after the scheduled time to see the per-platform result and any error.
5. `get_usage` before anything that spends credits.

`create_post` accepts an `idempotency_key`. Reusing it with the same arguments returns the first post instead of creating a second one, which matters when an assistant retries.