MCP
MCP tools
Every tool the server offers, its parameters, the scope that unlocks it, and whether it writes.
Tool names are a contract, like REST paths: they never change meaning within v1. The publishing tools carry the names agents already know, so a prompt written for another publishing server works here unchanged. Every tool answers the same payload the REST route would, in both the text block and structuredContent.
tools/list returns only the tools the key is scoped for. Write tools take an optional idempotencyKey; see Idempotency.
With every scope, a deployment with default settings offers 27 of the tools below. list_instagram_profiles is the 28th and is listed only where the deployment enables platform-derived data.
Publishing
list_connections
List connected social accounts. Scope connections:read, read-only.
Every connected account with tokenStatus, lastError and lastSuccessfulPost. Call it first to get the connectionIds that create_post needs. An expired connection must be reconnected in the app.
list_posts
List posts. Scope posts:read, read-only.
| Parameter | Type | Notes |
|---|---|---|
status | enum | draft, scheduled, publishing, published, partial_published, failed, cancelled |
platform | string | One platform id |
from, to | ISO 8601 | Window on scheduledAt |
page | integer | Default 1 |
limit | integer | Default 50, max 200 |
Newest first, paginated; read total before saying how many there are.
create_post
Create a post. Scope posts:write, writes.
| Parameter | Type | Notes |
|---|---|---|
content | string | Required, 1 to 10,000 characters |
connectionIds | string[] | Required, 1 to 20 |
scheduledAt | ISO 8601 | Omit for a draft |
mediaUrls | string[] | Up to 10 public https URLs |
mediaIds | string[] | Up to 10, from complete_media |
platformSettings | object | Per-platform settings keyed by platform |
variants | object | { [platform]: { content } } |
requireApproval | boolean | Queue for approval anyway |
idempotencyKey | string | Up to 255 characters |
Same rules as POST /posts: Instagram needs media, unknown settings are refused with PLATFORM_SETTING_UNKNOWN, and the approval rule applies with an APPROVAL_REQUIRED warning.
get_post
Get one post. Scope posts:read, read-only.
| Parameter | Type | Notes |
|---|---|---|
postId | uuid | Required |
One post with targets. A failed target carries the platform error verbatim.
update_post
Edit a post. Scope posts:write, writes.
| Parameter | Type | Notes |
|---|---|---|
postId | uuid | Required |
| … | Every create_post field, all optional | |
idempotencyKey | string |
Only the fields passed change. POST_NOT_EDITABLE once the post is publishing, published or cancelled.
delete_post
Cancel a post. Scope posts:write, writes.
| Parameter | Type | Notes |
|---|---|---|
postId | uuid | Required |
idempotencyKey | string |
Cancel a draft or scheduled post; the row is kept as cancelled. Nothing is removed from any platform.
get_upload_url
Get a media upload URL. Scope media:write, writes.
| Parameter | Type | Notes |
|---|---|---|
kind | enum | image or video, required |
contentType | string | Required |
bytes | integer | Required, exact length |
idempotencyKey | string |
A presigned PUT valid for 15 minutes (15 MB images, 500 MB video). PUT the bytes, then complete_media, then pass the id as mediaIds.
complete_media
Complete a media upload. Scope media:write, writes.
| Parameter | Type | Notes |
|---|---|---|
mediaId | uuid | Required |
idempotencyKey | string |
Confirms the upload landed. MEDIA_NOT_READY if the bytes are not there yet.
delete_media
Delete a media asset. Scope media:write, writes.
| Parameter | Type | Notes |
|---|---|---|
mediaId | uuid | Required |
idempotencyKey | string |
Deletes the asset and its object. Only delete media no post still needs.
get_best_times
Get best posting times. Scope posts:read, read-only.
| Parameter | Type | Notes |
|---|---|---|
platform | string | Optional |
Slots from the workspace's own history plus per-platform priors; fromHistory says which.
post_stats
Get engagement for a published post. Scope posts:read, read-only.
| Parameter | Type | Notes |
|---|---|---|
postId | uuid | Required |
Delivery facts per target plus an engagement block. engagement is null with an unavailableReason when there is no reading; today that is the case on every deployment where platform-derived reads are off, and for every platform other than Facebook and Instagram.
profile_stats
Get profile stats for a connected account. Scope posts:read, read-only.
| Parameter | Type | Notes |
|---|---|---|
connectionId | uuid | Required |
The connection, its delivery record from our own log (publishedPosts, lastSuccessfulPost, lastError), and insights, which is null with an unavailableReason under the same conditions as post_stats.
Workflows and the assistant
list_workflows
List workflows. Scope workflows:run, read-only.
The workspace's automations: id, name, description, enabled, autonomy, triggers, templateKey, updatedAt. A disabled workflow can still be run manually.
run_workflow
Run a workflow. Scope workflows:run, writes.
| Parameter | Type | Notes |
|---|---|---|
workflowId | uuid | Required |
dryRun | boolean | Walk data and condition nodes, report what would be staged |
triggerMeta | object | Exposed to nodes as {{trigger.*}} |
idempotencyKey | string |
Queues a manual run and returns { runId, workflowId, status, dryRun }. Refused with plan_limit_reached when the daily run cap is used up, and with a budget message when the monthly AI budget is spent.
get_workflow_run
Get a workflow run. Scope workflows:run, read-only.
| Parameter | Type | Notes |
|---|---|---|
runId | uuid | Required |
Status (queued, running, succeeded, failed, skipped), times, costMicros (null until finished), summary, error and the steps in order. A step that staged an action for a human to confirm says so; it has not been performed.
ask_gloofy
Ask the overads assistant. Scope analytics:read, read-only.
| Parameter | Type | Notes |
|---|---|---|
question | string | Required, up to 4,000 characters |
One grounded answer from the workspace's assistant, with toolsUsed and any stagedActions. Costs model budget against the workspace, the same as chatting in the app. Staged actions have not been performed.
Recaps, drafts and approvals
get_weekly_recap
Get the weekly recap. Scope analytics:read, read-only.
| Parameter | Type | Notes |
|---|---|---|
from, to | YYYY-MM-DD | Both or neither; default the last 7 full days (UTC), ending yesterday |
One recap of the window set against the window of the same length just before it. ads and posts are each { data, provenance }. ads carries the change in impressions, clicks, results, spend and revenue, cost per result and ROAS, and a line per ad account; money is in minor units, and when the window spans more than one currency it appears per account only. The top and bottom three ads are included only where the deployment enables platform-derived data; otherwise they are null and named in notIncluded. posts carries deliveries per channel against the prior window, failed deliveries, and the posts that measured above or below the account's usual results; it needs posts:read as well, and without it is named in notIncluded. A null figure was not measured, not zero.
what_worked
Find what worked. Scope analytics:read, read-only.
| Parameter | Type | Notes |
|---|---|---|
from, to | YYYY-MM-DD | Both or neither; default the last 30 days |
The posts and ads that beat this workspace's own baseline, each with its figure and the figure it was compared with. A post is listed when its result is at least 1.5 times the median of the same account's earlier posts; an ad when its cost per result (3 results or more) or its ROAS beat its own account's figure for the window by 1.5 times or more, with each account's figures in byAccount. The ad list is present only where the deployment enables platform-derived data; otherwise it is null and named in notIncluded. brandMemory carries the performance facts saved to the brand memory. An empty list under a provenance of collected means nothing cleared the bar, which is not the same as no data; verdicts.unmeasured counts posts that could not be judged.
draft_on_brand_post
Draft an on-brand post. Scope posts:write, writes.
| Parameter | Type | Notes |
|---|---|---|
topic | string | Required, 1 to 2,000 characters: a topic, a brief or notes |
connectionIds | string[] | Required, 1 to 20, from list_connections |
idempotencyKey | string | Up to 255 characters |
Writes copy in the brand's voice from the brand memory, one version per targeted channel within that channel's character limit, and saves it as a draft. It never schedules and never publishes; in a workspace that requires approval the result carries an APPROVAL_REQUIRED warning, because the draft will wait for approval once it is scheduled. Text only. Connections must be on a live channel (Instagram, Facebook, LinkedIn, X, Bluesky, Mastodon and Pinterest), otherwise CHANNEL_NOT_LIVE; an expired connection answers CONNECTION_EXPIRED. Copy still over a limit after one rewrite is refused with TOO_LONG and nothing is saved. Uses AI budget against the workspace. Returns the draft id, each channel's text with its length and limit, and a link to the draft in the app.
list_waiting_approvals
List items waiting for approval. Scope posts:read, read-only.
Posts pending approval (soonest due first) and actions the assistant staged for confirmation (newest first), each with a link into the app where it is approved. Nothing listed has been published or performed. counts are the true totals; items is capped at 20 and truncated says when more are waiting. Staged actions also need analytics:read; without it they are named in notIncluded and counts.proposals is null.
Analytics
list_ad_accounts
List connected ad accounts. Scope analytics:read, read-only.
The ad accounts this workspace connected, each with its metrics-sync state.
get_metrics_summary
Get ad metrics totals. Scope analytics:read, read-only.
| Parameter | Type | Notes |
|---|---|---|
from, to | YYYY-MM-DD | Both or neither; default last 30 days |
accountId | uuid | Optional |
Totals over a window. Money in minor units as a string; null counters are missing readings.
list_daily_metrics
List ad metrics by day. Scope analytics:read, read-only.
| Parameter | Type | Notes |
|---|---|---|
from, to | YYYY-MM-DD | |
accountId | uuid | |
limit | integer | Default 500, max 2,000 |
Per-day totals, newest first, split by account, platform and currency.
list_crawled_sites
List crawled sites. Scope analytics:read, read-only.
Sites overads crawls for this workspace, each with a crawl block.
list_crawled_pages
List crawled pages. Scope analytics:read, read-only.
| Parameter | Type | Notes |
|---|---|---|
siteId | uuid | |
limit | integer | Default 200, max 1,000 |
Tracked URLs and how the last visit ended. Twelve state values; only the fetched_* ones say anything about the page.
get_page_timeline
Get one page visit history. Scope analytics:read, read-only.
| Parameter | Type | Notes |
|---|---|---|
pageId | uuid | Required |
limit | integer | Default 200, max 500 |
Every visit, newest first, including the ones that returned nothing.
list_page_changes
List detected page changes. Scope analytics:read, read-only.
| Parameter | Type | Notes |
|---|---|---|
siteId | uuid | |
pageId | uuid | |
limit | integer | Default 100, max 500 |
Visits where a detector fired, with before and after strings. Check provenance.emptyMeans before reading an empty list as no change.
list_instagram_profiles
List tracked Instagram profiles. Scope analytics:read, read-only. Gated: Absent from tools/list unless the deployment enables platform-derived sources.
Tracked handles and the last reading of each. Counts are null when Instagram withheld them.