Tool reference - PublishBuddy

Every tool runs with the permissions of the user behind the token or sign-in, inside the request’s workspace. Tools only see the profiles that user can access: every profile for the workspace owner, and for other members, admins included, the profiles they have been given access to plus public profiles. Post tools work on posts for those profiles and on drafts without a profile. Profile-scoped tools take profile UUIDs; call list_profiles first to get them. Dates are ISO 8601 and UTC unless the tool says otherwise. Credits are only charged for tools that call an AI model. See Credits. The AI Studio tools are free at this layer: AI Studio charges the model’s quote inside the generation, and quote_media tells you the figure first (see Media (AI Studio)).

Profiles and preferences

Tool	What it does	Credits
`list_profiles`	Lists the workspace’s social profiles you can access: name, network, avatar, connection status, and UUID. Start here.	0
`get_user_preferences`	Returns your saved content preferences: tone, content themes, hashtag count, emoji level, call-to-action style, preferred platforms. Assistants read this before drafting.	0
`save_user_preferences`	Saves or updates those preferences. All fields optional; only the ones you pass change.	0

Posts

Tool	What it does	Credits
`create_post`	Creates a draft for one profile (`profile_id`) or the same draft for several (`profile_ids`: one post per profile, all sharing a `group_id`): caption (optional when media or a link is attached), post type, media from the library by UUID, a link, labels, and follow-up comments (`comments`, each with a `text` and an optional delay). Returns the post, including its ID, or `{ group_id, posts }` for several profiles. Nothing is published until you schedule, queue, or publish it.	0
`update_post`	Changes a post’s caption, media, or labels. Only while the post is a draft or waiting to publish.	0
`delete_post`	Deletes a draft or waiting post. Irreversible.	0
`get_post`	Reads one post by ID: status, scheduled and published times, the error message when publishing failed, the link to the published post and its metrics, media, labels, and comments.	0
`list_posts`	Lists the workspace’s posts by status (`draft`, `needs_approval`, `waiting`, `publishing`, `published`, `failed`; every status when `statuses` is omitted) with optional profile, text, label, group, and date filters (`publish_range` and `published_range` take calendar days, `YYYY-MM-DD`). Returns the posts, the total, and a count per status. Up to 50; narrow with filters rather than paging.	0
`get_draft_posts`	Lists drafts for the given profiles (every profile you can access when `profile_ids` is omitted), optionally filtered by last-updated date range. Default 20.	0
`get_scheduled_posts`	Lists posts with a publish time for the given profiles (every profile you can access when `profile_ids` is omitted): the ones waiting to publish by default, or the statuses you pass in `statuses` (`["waiting", "failed"]` shows the week’s problems next to the plan). Optional date range. Default 20.	0

Scheduling and publishing

Tool	What it does	Credits
`schedule_post`	Schedules a draft for a specific date and time (ISO 8601) on a profile, or moves a scheduled or queued post to a new time. Published, publishing, and failed posts are refused. Refused when your access to that profile requires approval.	0
`add_post_to_queue`	Adds a draft to a profile’s posting queue at the top or bottom; the next free timeslot publishes it. The profile needs Queue Publish Times (set them in the dashboard or with `set_queue_times`). Refused when your access to that profile requires approval.	0
`get_queue_times`	Reads a profile’s Queue Publish Times, the weekly timeslots its queue publishes into: each slot’s day (1 = Monday, 7 = Sunday) and time in your account’s timezone, the schedule grouped by day, and how many posts are waiting in the queue.	0
`set_queue_times`	Sets a profile’s Queue Publish Times, the same schedule as the dashboard’s. Pass `times` (HH:MM) with optional `days` for the same times on several days, or `timeslots` (`day_of_week`, `time`, optional `label`) for a schedule that differs by day. `mode` `replace` (default) swaps the whole schedule; `add` keeps the existing slots and adds new ones, skipping any already there. Times are in your account’s timezone. Posts already waiting in the queue are re-timed to the new schedule, and one that no longer fits a slot waits until the queue has room. At most 336 timeslots. Needs admin access to the workspace.	0
`publish_now`	Publishes a post right away: a draft, a post waiting for approval, a scheduled or queued post, or a failed one. The post goes out on the publisher’s next run, within a minute. A draft without a profile needs `profile_id`. Refused for published and recurring posts and when your access to the profile requires approval.	0
`retry_post`	Re-runs a failed post: back to waiting with the error cleared, published right away when it was scheduled, in its slot when it was queued. Only failed posts.	0
`unschedule_post`	Returns a scheduled or queued post (or one waiting for approval) to draft. It keeps its content and media and does not publish until it is scheduled or queued again.	0

Media

Tool	What it does	Credits
`list_media`	Lists the media library, newest first: id, name, label, link, size, dimensions, duration, and folder. Filter by `folder_id` (`root` for files in no folder) and search by name or label. The id is what `create_post` and `update_post` take in `media_uuids`. Up to 50.	0
`upload_media`	Saves an image or video from a public http(s) URL into the library and returns it, including its id. JPEG, PNG, GIF, WebP, MP4, and QuickTime up to 50 MB; the server refuses private addresses, other file types, and larger files. Optional `name`, `label`, and `folder_id`.	0
`request_media_upload`	For files on the user’s own computer. Returns a short-lived signed `upload_url` (valid 30 minutes) and a ready `curl` command. POST the files to it as multipart `files[]`, up to 10 per request and 200 MB each; the response is `{ data: [media] }`, and each id goes in `media_uuids`. The URL takes several uploads until it expires and needs no API key, so keep it private. Optional `label` and `folder_id` apply to every file. Needs the media library (Pro or Business). For a file at a public URL, use `upload_media`.	0

Brand Kit

Tool	What it does	Credits
`list_brand_kits`	Lists the workspace’s Brand Kits: id, name, logo, and the profiles each one is assigned to.	0
`get_brand_kit`	Reads a Brand Kit: voice instructions, the voice summary derived from past posts, colours, logo, font, emoji preference, and assigned profile ids. Pass `brand_kit_id`, or `profile_id` for the kit assigned to that profile; with neither you get the workspace’s only kit.	0

Workspace

Tool	What it does	Credits
`get_workspace_overview`	The workspace at a glance: connected accounts, posts scheduled this week, failed posts by network, posts waiting for approval, what was published in the last 90 days, last week’s top post, the best time to post, the AI credit balance, and the next five upcoming posts. Optional `profile_ids`.	0
`list_workspaces`	The workspaces you belong to, with their ids and which one the request is pinned to. Set the `X-Workspace-Id` header to one of these ids to work in another workspace.	0

Analytics

Tool	What it does	Credits
`get_engagement_summary`	Published posts, likes, reach, engagements, graphs, and best time to post for one profile (with previous-period comparison; `for_all_time` has no previous period, so its comparisons are null) or the whole workspace. Takes a preset timeframe (`last_7_days` through `for_all_time`) or a custom date range. A workspace-wide range with more than 10,000 published posts is refused with a hint to narrow it or ask per profile.	0
`get_profile_metrics`	The audience side of one profile over a preset timeframe (`last_30_days` by default): new followers with the change against the previous period, the followers series, link clicks, video views, and the gender, age, country, and city breakdowns.	0
`get_top_posts`	Posts ranked by a metric for the given profiles (every profile you can access when `profile_ids` is omitted). `sort_direction: desc` for best, `asc` for worst. 1 to 20 posts, optional date range in whole days (the end date is included). Not charged when nothing matches.	1
`get_best_posting_times`	Ranked days and hours with expected engagement, from the profiles’ own history (every profile you can access when `profile_ids` is omitted). Defaults to the last 30 days; long ranges are sampled from the newest 5,000 posts.	0
`get_hashtag_performance`	Top hashtags by engagement and reach over a date range, for one profile or, when you leave out `profile_id`, the whole workspace. Up to 50.	0

AI images

Image generation runs in the background. generate_image and edit_image return a job ID immediately; poll check_image_generation_status until it reports the finished image, which is saved to the media library and can be attached to a post by UUID. For AI Studio’s models, videos, carousels, and a credit quote before the call, see Media (AI Studio).

Tool	What it does	Credits
`generate_image`	Generates an image from a prompt, with optional style, aspect ratio (square by default), and target platform. Takes roughly 15 to 30 seconds.	17
`edit_image`	Edits an existing image with a prompt: either the output of a previous generation or edit job, or an image already in the media library.	17
`check_image_generation_status`	Returns the job’s status and, when complete, the image URL.	0

Media (AI Studio)

These tools run on AI Studio’s rails: the same models, prices, Brand Kit theming, and background jobs as the AI Studio page in the dashboard, so a generation started from an MCP client is the same generation the Studio would make, and its result is saved to the media library. They need a plan with AI Studio (Pro or Business); without it the call returns a 402. A job, then its status. Images and videos run in the background. generate_media and animate_image return at once with a generation_id and status: pending; call get_media_generation with that id until it reports succeeded (with media.id and media.url) or failed (with error_code and error_message). A carousel takes two steps: generate_media returns the slide copy at once as a draft (draft_slides), and once the copy is approved, finalize_carousel renders the slides (processing, then succeeded with slides in order) and, when profile_ids is given, creates one draft post per profile from them, reported in post_ids. Text comes back finished (succeeded, with the variations in text). media.id and each slide’s id are library ids: what create_post takes in media_uuids, and what animate_image takes as a source. Credits. The tool calls cost 0 credits at this layer. AI Studio charges the model’s quote inside the generation when it is submitted (the draft quote when it writes carousel copy) and refunds it when the generation fails; credits_quoted, credits_charged, and credits_refunded on the generation show the figures. Call quote_media with the arguments you are about to send first: it returns credits_required, the workspace’s credits_remaining, and a cheaper_option when a cheaper model of the same kind could run the request. A request the balance cannot cover is refused with the quote, the balance, and the cheaper model in the error, and nothing is charged.

Tool	What it does	Credits
`generate_media`	Creates an image, a video, a carousel, or text with an AI Studio model. `kind` (`image`, `video`, `carousel`, `text`) and `prompt` (up to 4,000 characters) are required. `model` is a key from `list_media_models`; leave it out for the plan default (`gpt-image-2` for an image, `seedream-v4.5` for an image with references, `kling-2.5-turbo-pro` for a video). `aspect_ratio` is one of the model’s (`1:1` for images and `9:16` for videos by default) and `duration_seconds` one of the model’s lengths (the shortest by default, usually 5). `profile_id` applies that profile’s Brand Kit (its palette and font go into the prompt, its colours, font, and logo onto carousel slides, its voice into copy and captions); `brand_kit_id` names a kit instead. `reference_media_ids` gives up to 4 library image UUIDs for the image model to follow, which switches it to its editing variant. Carousels take `template_key` (`tips-list` by default, `bold-statement`, `quote`, `step-by-step`, `hook-reveal`, `title-content-cta`) and `slide_count` (2 to 8, default 6); text takes `platforms`, `text_mode` (`post` by default, `hook`, `hashtags`, `repurpose`, `rewrite`), and `source_text` for repurposing or rewriting. Returns the generation: `pending` for an image or video, `draft` with `draft_slides` for a carousel, `succeeded` with `text` for text.	0 (the model’s quote is charged inside AI Studio)
`animate_image`	Turns an image into a short video with an image-to-video model: `wan-2.5-image-to-video` by default, or another image-to-video `model` from `list_media_models` (the ones with `requires_reference_image`). The output keeps the image’s shape. Give `media_content_id` (a library file, an attachment, or a generated image) or `generation_id` (a succeeded image generation from `generate_media`), describe the motion in `prompt`, and optionally pick `duration_seconds` (the shortest by default, 5). Videos, and images whose upload was never confirmed, are refused. Returns `pending`; read it back with `get_media_generation`.	0 (the model’s quote per second is charged inside AI Studio)
`finalize_carousel`	Renders a carousel draft from `generate_media` into its slide images, themed by the Brand Kit, and, when `profile_ids` is given (up to 20), creates one draft post per profile from the slides once the render lands, with your `caption` (up to 2,200 characters; write it from the slides) and optional `labels`. The posts share a `group_id`. Only a `draft` carousel can be finalized; call it after the user approved the slide copy. Returns `processing`; `get_media_generation` reports `succeeded` with `slides` and `post_ids`. Without `profile_ids` the slides are rendered only, for a later `create_post`. Not working in production at the moment: the render can’t run on the server yet, so `get_media_generation` reports `failed`.	0
`get_media_generation`	Reads a generation back by `generation_id`: `kind`, `status` (`pending`, `processing`, `succeeded`, `failed`, `draft`), the model, the prompt and parameters, `credits_quoted`, `credits_charged`, and `credits_refunded`; `media` (`id`, `url`, `width`, `height`) once an image or video succeeded; `slides` (in position order) and `post_ids` for a finalized carousel; `draft_slides` for a carousel draft; `text` for a text generation; `error_code` and `error_message` when it failed. Only generations of the request’s workspace.	0
`quote_media`	What a `generate_media` or `animate_image` call would cost before you make it. Pass `tool` (`generate_media` or `animate_image`) with the arguments you would pass to it. Returns the resolved `model_key` and `model_label`, `credits_required`, the workspace’s `credits_remaining`, and `cheaper_option` (`model_key`, `model_label`, `credits_required`) when a cheaper model of the same kind could run the request, or `null`. Charges nothing and creates nothing.	0
`list_media_models`	The AI Studio models the workspace’s plan can use, all of them or only `image` or `video` models (`kind`): `key`, `label`, `description`, `kind`, `aspect_ratios`, `durations`, `max_reference_files`, `requires_reference_image` (the image-to-video models `animate_image` uses), `min_plan`, and `credits` for a default request, with `credits_note` saying what that request is (one image, or the shortest clip).	0

Pick the model by what the user wants:

You want	Pass	Credits
A quick draft, to explore a prompt	`flux-2`	4 per image
A photoreal image	`seedream-v4.5`	11 per image
Readable text in the image: quote cards, posters, promo graphics	`ideogram-v3` or `gpt-image-2`	16 or 14 per image
Flagship quality (Business plan)	`nano-banana-pro`	40 per image
A short clip from a prompt	`kling-2.5-turbo-pro`	92 for 5 seconds
An existing image set in motion, through `animate_image`	`wan-2.5-image-to-video`	132 for 5 seconds
A carousel	`kind: carousel`	5 for a six-slide draft; rendering it with `finalize_carousel` is free, but rendering isn’t working in production at the moment
Captions, hooks, or hashtags	`kind: text`	1 for one network, more for several

These are the figures list_media_models returned when this page was written, for one image or the shortest clip; a longer clip costs more per second, and the tool returns the current prices.

Web pages

Tool	What it does	Credits
`fetch_url`	Reads a public web page or text file and returns its `title`, its readable `text` (scripts, navigation, headers, footers, and asides removed), the `final_url` after redirects, `chars`, and whether the text was `truncated`. Up to 20,000 characters and 5 MB; HTML and plain text only, so for a link to an image or a video use `upload_media`. The server refuses private addresses, as it does for `upload_media`. Use it when the user gives a link to work from: to summarise it, repurpose it, or write about it.	0

Visual insights

These tools work on posts that have already been published and analysed. They are useful for answering “why did this work?” and for turning what worked into a brief for the next post.

Tool	What it does	Credits
`analyze_post_visuals`	Structured visual features for one published post: palette, detected objects, text overlays, transcript phrases. `lite` reads the cached extraction; `quick` and `deep` re-analyse with a larger model and consume a daily drill-down quota.	0
`analyze_post_drivers`	Explains why a post performed by comparing its visual features against the profile’s last 90 days of posts.	0
`search_library`	Searches published posts by visual features: colors, objects, on-screen text, or spoken phrases (every profile you can access when `profile_ids` is omitted). Colour words filter the palette, quoted phrases match on-screen text, any other word is looked up as an object label. Up to 50 results.	0
`build_creative_brief`	Intersects the visual features of several reference posts into a brief, a rendered prompt, and ready-to-use arguments for `generate_image`.	0
`reextract_visuals`	Re-runs feature extraction for up to 50 posts when a search returns too few matches or an extraction looks wrong.	0

Prompts

The server also registers five prompts. Claude Desktop, Claude Code, and Cursor list them as slash commands; each expands to a ready-to-send request that uses the tools above.

Prompt	Argument	What it asks for
`plan-week`	none	A plan for next week across every connected account: one idea per day, with the best time for each.
`report`	`range` (optional, default “last 30 days”)	An engagement summary for the period: what grew, what dropped, and the three best posts.
`repurpose`	`text` (required)	One post per connected network from a pasted article, newsletter, or transcript, within each network’s length limit.
`why`	`post` (a `social_post_id` or a short description)	What made the post work: its visuals, timing, and wording.
`ideas`	`topic` (required)	Five post ideas about the topic for the connected accounts.

Confirmation and safety

The server does not pause for confirmation itself; that is your client’s job, and every major client asks before running a tool unless you have allowed it. Each tool tells the client whether it is read-only, whether it can change or remove something that can’t be undone (destructiveHint: editing, deleting, scheduling, publishing, and spending AI credits on a generation), and whether it reaches outside your workspace (openWorldHint: publishing to social networks and fetching public URLs). Claude asks before every destructive tool. Three properties make the write tools safe to allow:

create_post only ever creates a draft. Publishing requires a second, explicit call to schedule_post, add_post_to_queue, or publish_now.
publish_now is the only tool that publishes without a scheduled time, and the server never calls it on its own. retry_post only re-runs a post that already failed, and unschedule_post only moves a post back to draft.
delete_post refuses anything that is publishing or already published. Nothing deletes media, folders, profiles, or team members.

Among the AI Studio tools, generate_media and animate_image are the two that spend credits, at the model’s AI Studio quote (from 4 credits for a FLUX.2 draft image to 92 for five seconds of Kling 2.5 Turbo Pro). Before running either, call quote_media with the same arguments and show the user credits_required, credits_remaining, and the cheaper_option; the in-app agent does exactly that on its confirmation card. finalize_carousel is free, but with profile_ids it creates draft posts, so treat it like create_post. generate_image and edit_image cost a flat 17 credits each. Revoke the token from User Settings → Login & Security at any time to cut off every client using it, and disconnect a signed-in app under Connected apps on the same page.

​Profiles and preferences

​Posts

​Scheduling and publishing

​Media

​Brand Kit

​Workspace

​Analytics

​AI images

​Media (AI Studio)

​Web pages

​Visual insights

​Prompts

​Confirmation and safety