hermoso

endpoint

https://app.hermoso.ai/mcp

protocol

streamable-http ·2025-06-18

authentication

none observed

public key

none — nobody has proven they own this listing

karma

0 · newcomer

Price is per tool, not per server. An agent whose handshake is open can hold tools that demand a key or a payment, and one figure for the whole agent sends callers into a wall.

• enable_tools unknown never probed

  LIST a group of tools that is not in this session's roster. IT IS NOT HOW YOU REACH A TOOL — call_tool runs any Hermoso tool whether or not it is listed, and that works everywhere. Use this when the session will use MANY tools from one area and you want them in your list. WORKS ON CLIENTS THAT RE-READ THE TOOL LIST (stdio, the CLI, Cursor, Claude Code); a host that fixed its roster at connect time — claude.ai and ChatGPT do — will not show the new tools until it reconnects, and this tool says so in its reply rather than reporting a success you cannot use. The connect-time route that always works is `?tools=all` on the server URL. The default roster is CORE-FIRST: the core tools plus a few that make the connection drivable. Every other tool is held out of the LIST on SIZE alone — the whole registry is several hundred thousand tokens of schema re-sent on every turn, and a roster far past the 30-50 tool mark measurably degrades tool choice. The heaviest groups are `ads`, `analytics`, `channel_admin`: paid-campaign management is most of the total schema weight across eleven ad platforms. NOTHING held out is unfinished or unsafe, and nothing is unreachable — find_tools finds it and call_tool runs it. CALL THIS WHEN A WHOLE AREA IS IN PLAY. If the user settles into building, budgeting, targeting or reporting on ad campaigns, call enable_tools({groups:['ads']}) and the tools appear. If they ask about their own site or product analytics, a tag/tracking container, or how a search engine crawls, indexes or ranks their site, call enable_tools({groups:['analytics']}). Groups: core, research, create, channels, channel_admin, analytics, ads, files, workspace — or 'all'. Free, instant, and it never turns anything off.

  mcp-tool

  12345678910111213141516

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "groups"
    ],
    "properties": {
      "groups": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "Groups to switch on, e.g. ['ads']. Unknown names are refused by name rather than ignored."
      }
    }
  }

  arguments 16 lines copy
• find_tools unknown never probed

  Search EVERY Hermoso tool — your starting list is deliberately short, and everything else in the product is here — by name, task or group. Each row gives the tool's PARAMETERS in one line, its CREDIT COST (free means free on every plan; a tool that runs a model quotes the live per-model figure) and its recent HEALTH on this server (failure rate and typical duration, or "no recent calls", which means unseen and not broken). Use it the moment the user asks for something you do not see a tool for (a campaign, an ad set, a lead form, a click-to-WhatsApp ad, a report, keywords, audiences): a tool missing from your list is NEVER proof the feature is missing. Then run the tool with call_tool. A tool that is failing or needs a connector this workspace has not made is ranked last and marked, never hidden — pass onlyHealthy:true if you want those left out. Free, read-only.

  mcp-tool

  12345678910111213141516171819202122

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "group": {
        "type": "string",
        "description": "limit to one group: core, research, create, channels, channel_admin, analytics, ads, files, workspace"
      },
      "limit": {
        "type": "number",
        "description": "how many to return (default 12, max 40)"
      },
      "query": {
        "type": "string",
        "description": "words from the task or the tool name, e.g. \"lead form\", \"whatsapp\", \"google ads keyword\", \"meta insights\""
      },
      "onlyHealthy": {
        "type": "boolean",
        "description": "leave out tools that are failing their recent calls or that need a connector this workspace has not made. Default false — nothing is hidden unless you ask, because a missing row reads as a missing capability."
      }
    }
  }

  arguments 22 lines copy
• call_tool unknown never probed

  Run ANY Hermoso tool by name — including the paid-campaign, analytics and channel-admin tools that are not in this session's starting list — with the same permissions, the same account and the same result as calling it directly. Get the exact `name` and its `args` from find_tools first. This is the route on hosts that cannot reload their tool list mid-conversation (claude.ai, ChatGPT): enable_tools switches a group on server-side, but such a host keeps the list it fetched at connect time. Arguments are validated against the tool's own schema and a mistake is answered with the expected parameters, not a silent default. Refused by name, with the way out, when the tool needs a connector this workspace has not made or is withheld by the host's own policy.

  mcp-tool

  123456789101112131415161718192021

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "name"
    ],
    "properties": {
      "args": {
        "type": "object",
        "description": "the tool's arguments as an object, exactly as its own schema takes them",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {}
      },
      "name": {
        "type": "string",
        "description": "the tool name exactly as find_tools returned it, e.g. create_meta_lead_form"
      }
    }
  }

  arguments 21 lines copy
• post_to_bluesky unknown never probed

  Publish a post to Bluesky as the connected account. Text up to 300 characters — Bluesky ALSO caps a post at 3000 UTF-8 bytes, so an emoji-heavy post can be under 300 characters and still be refused; Hermoso checks both before spending the round trip and says which limit and by how much. MEDIA: either up to 4 images (imageUrls + altText) OR one MP4 video (videoUrl + videoAlt), never both — a Bluesky post record carries a single embed and images and video are two different embed types. Video is MP4 only, up to 300MB at Bluesky's end (Hermoso can fetch up to 150MB from a URL), with optional WebVTT caption tracks; the aspect ratio is measured from the file. Bluesky requires a CONFIRMED EMAIL on the account before it will process any video — if it is unconfirmed you get a refusal saying so, and reconnecting will not help. Links in the text are made clickable automatically. LINK CARDS: Bluesky does NOT scrape links, so a URL posted bare renders as plain blue text — the client composing the post has to build the card. Hermoso builds one AUTOMATICALLY when the post has a URL and NO media: it fetches the page, uses its title/description and uploads its image as the card thumbnail. Pass linkCard:false to suppress it, or linkCard:{uri,title,description,thumbUrl} to control it (give both title and description and the page is not fetched at all). A POST CARRIES ONE EMBED, so a card and images/video cannot both ride: if you pass linkCard explicitly ALONGSIDE media the call is REFUSED by name rather than silently dropping one, and if the URL was merely in the text the MEDIA WINS and the reply says the card was skipped (the link stays clickable either way). Returns the post's public bsky.app URL. Connect at Settings ▸ Connectors ▸ Bluesky, or here with connect_connector, with a handle and an APP PASSWORD.

  mcp-tool

  1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "text"
    ],
    "properties": {
      "text": {
        "type": "string",
        "description": "The post, up to 300 characters / 3000 UTF-8 bytes."
      },
      "langs": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "BCP-47 language tags, e.g. ['en']."
      },
      "account": {
        "type": "string",
        "description": "WHICH connected account of this channel to post as — its @handle or id from list_connector_accounts. Needed only when the brand has more than one bluesky account connected (several and none named is refused by name, never guessed); omit when there is one."
      },
      "altText": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        ],
        "description": "Alt text — an ARRAY, one per image in the same order, or a single STRING to describe every image with it. WRITE ONE: Bluesky’s own lexicon makes `alt` a REQUIRED property of every image, so a post without it is undescribed by design rather than by omission, and Bluesky users expect it. No maximum length is published, so nothing is truncated."
      },
      "captions": {
        "type": "array",
        "items": {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {}
        },
        "description": "Up to 20 WebVTT caption tracks: [{lang:'en', url:'https://…/en.vtt'}] or [{lang:'en', content:'WEBVTT\\n\\n00:00…'}]. Each file is capped at 20000 bytes."
      },
      "linkCard": {
        "anyOf": [
          {
            "type": "boolean"
          },
          {
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {}
          }
        ],
        "description": "Rich link card (`app.bsky.embed.external`). OMIT for the default (a card is built automatically when the post has a URL and no media). `false` never builds one. `true` builds one from the first URL in the text. An object {uri,title,description,thumbUrl} overrides any field — supply BOTH title and description and the page is never fetched. Cannot be combined with imageUrls/videoUrl: a post has ONE embed, so an explicit linkCard beside media is refused."
      },
      "videoAlt": {
        "type": "string",
        "description": "Alt text describing the video, for accessibility."
      },
      "videoUrl": {
        "type": "string",
        "description": "One public MP4 URL. Cannot be combined with imageUrls. Bluesky transcodes it, which takes a minute or two."
      },
      "imageUrls": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "Up to 4 public image URLs to attach. Cannot be combined with videoUrl."
      },
      "platformCover": {
        "type": "boolean",
        "description": "VIDEO COVER. Bluesky has no cover setting and shows the video’s FIRST frame, so by default Hermoso checks it and, only when that frame is blank (a template ad’s empty opening card), sends Bluesky a copy with the first frame replaced by the video’s best frame. Your Library file is never changed. true = send the file exactly as it is."
      }
    }
  }

  arguments 83 lines copy
• post_to_telegram unknown never probed

  Publish to a Telegram channel, group or chat as the brand's own bot. WHICH CHAT IS ALWAYS REQUIRED AND IS NEVER GUESSED: pass chatId as the public channel's @username (e.g. @hermosoai) or its numeric id (a group is negative; a supergroup or channel starts with -100). There is no default and there cannot be one — the Telegram Bot API publishes no method that lists the chats a bot belongs to, so Hermoso genuinely cannot know them. list_telegram_chats reports the chats that have MESSAGED the bot in the last 24 hours, which is a shortcut for finding an id and is NOT a roster: a chat missing from it can still be posted to. TEXT: up to 4096 characters on a text-only message, but only 1024 the moment ANY photo or video is attached — a caption is not a message, and Hermoso refuses the over-long one before spending the round trip and says which budget applied. MEDIA: one image (imageUrl), one video (videoUrl), or an ALBUM of 2–10 (imageUrls, in order) in which photos and videos may be MIXED — pass a videoUrl alongside imageUrls and it joins the album as one more item. Hermoso uploads the bytes rather than handing Telegram a link, which is what buys the larger ceilings: 10MB per photo and 50MB per video, where a link would be 5MB and 20MB. THE BOT MUST BE IN THE CHAT — an administrator with Post Messages for a channel, an unrestricted member for a group; if it is not, Telegram refuses and the error says to add it rather than to reconnect. Returns the message id and, for a PUBLIC chat, its t.me link — a private group has no public web link, so `url` comes back null rather than as a link that would 404 for whoever you hand it to. 0 credits. Connect at Settings ▸ Connectors ▸ Telegram, or here with connect_connector, by pasting a bot token from @BotFather.

  mcp-tool

  123456789101112131415161718192021222324252627282930313233343536373839404142434445464748

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "chatId"
    ],
    "properties": {
      "text": {
        "type": "string",
        "description": "the message. ≤4096 characters on its own; ≤1024 once any image or video is attached."
      },
      "chatId": {
        "type": "string",
        "description": "REQUIRED — the destination: a public channel's @username, or the numeric chat id. Never guessed; ask the user, or use list_telegram_chats."
      },
      "silent": {
        "type": "boolean",
        "description": "deliver without a notification sound (Telegram’s disable_notification). This is NOT a visibility setting — the message is just as visible."
      },
      "account": {
        "type": "string",
        "description": "WHICH connected account of this channel to post as — its @handle or id from list_connector_accounts. Needed only when the brand has more than one telegram account connected (several and none named is refused by name, never guessed); omit when there is one."
      },
      "imageUrl": {
        "type": "string",
        "description": "one image (≤10MB after upload)"
      },
      "videoUrl": {
        "type": "string",
        "description": "one video (≤50MB). Passed alongside imageUrls it joins the album as one more item."
      },
      "imageUrls": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "an ALBUM of 2–10 media, in order. Photos and videos may be mixed — Telegram allows it."
      },
      "platformCover": {
        "type": "boolean",
        "description": "VIDEO COVER. Omit it (the default) and Hermoso sets the video’s best frame — the same frame as its Library thumbnail — as the cover (Telegram’s in-chat video cover). true = send no cover and let the platform pick (usually the first frame). A cover you pass yourself always wins."
      },
      "disablePreview": {
        "type": "boolean",
        "description": "suppress the link-preview card on a text-only post. Default is Telegram’s own behaviour (previews on)."
      }
    }
  }

  arguments 48 lines copy
• list_telegram_chats unknown never probed

  Find the chat ids this Telegram bot can be addressed by. STATE THE LIMIT WHENEVER YOU USE IT: this is NOT the list of chats the bot belongs to — the Bot API publishes no such method — it is every chat that SENT the bot an update in the last 24 hours, which is as long as Telegram keeps an update. A channel the bot posts to every day but nobody messages will NOT appear here, and its absence means nothing at all: post to it by @username or numeric id anyway. If the bot has an outgoing WEBHOOK configured the list is empty for that reason alone (Telegram: getUpdates "will not work if an outgoing webhook is set up"), and the reply says so rather than reading as an empty account. Nothing is consumed — no update offset is confirmed, so this cannot eat the bot’s pending updates. Free, 0 credits.

  mcp-tool

  12345678910

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "limit": {
        "type": "number",
        "description": "how many recent updates to scan, 1–100 (default 100)"
      }
    }
  }

  arguments 10 lines copy
• hermoso_capabilities unknown never probed

  Probe what this Hermoso account can do RIGHT NOW: available image/video model ids + their exact credit costs, aspect ratios, video durations, the recipe ids, and the canEdit/canAvatar flags. Call it when you need a specific model id, an exact cost, or a capability you are not sure of. It is NOT a prerequisite for rendering: generate_image, generate_video and render_ad all run with `model` omitted and route to the server’s own default. Read-only, free.

  mcp-tool

  12345

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {}
  }

  arguments 5 lines copy
• hermoso_credits unknown never probed

  Return the account credit balance, the credits this account has spent on the calls listed, those recent priced calls, and costModel — the one-sentence rule of what costs credits. THE RULE: only AI model runs and Ad Spy research spend credits; publishing, scheduling, ads management, analytics, comments, DMs and connectors are FREE on every plan (X is the single per-call exception). Check before kicking off paid generation; answer "does posting cost credits?" with NO.

  mcp-tool

  12345

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {}
  }

  arguments 5 lines copy
• buy_credits unknown never probed

  Out of credits? Top up with a credit PACK. Call with no argument to list the available packs (id · credits · price). If the account has a saved card and you have billing-admin rights, calling with `pack` quotes the exact charge and calling again with confirm:true AND the quote's quote_token charges the saved card instantly (same one-click top-up as the app — no redirect). If there's no saved card yet, you get a Stripe checkout URL to hand your human for the FIRST purchase; their card saves for one-click after that. Packs only; subscriptions are managed by a person in Settings → Billing. IF YOU ARE AN AGENT HOLDING YOUR OWN PAYMENT CREDENTIAL, there is a third path that needs no human at all: `POST /api/billing/machine-payment` with a `packId` answers HTTP 402 carrying an MPP challenge, and grants the pack once you authorise and retry with the credential — the same packs, the same prices, the same credits. `GET /api/billing/config` carries a `machinePayments` block listing the packs with their per-credit rates and saying whether that lane is enabled on this server. Most agents do NOT have their own credential yet, so the checkout link above remains the normal path. To stop running out entirely, turn on auto-reload with set_auto_reload (admin) — low balances then top themselves up from the saved card automatically.

  mcp-tool

  123456789101112131415161718

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "pack": {
        "type": "string",
        "description": "the pack id to buy (e.g. pack-2k) — omit to list the available packs first"
      },
      "confirm": {
        "type": "boolean",
        "description": "set true to actually charge the saved card for `pack` (required for the one-click charge; ignored on the checkout-link path)"
      },
      "quote_token": {
        "type": "string",
        "description": "the quoteToken returned by the quote step — REQUIRED (with confirm:true) to charge; it binds the exact pack + price you quoted (10-minute validity) and makes a retried confirm idempotent"
      }
    }
  }

  arguments 18 lines copy
• report_bug unknown never probed

  Report a bug in Hermoso to the team. Use this when something in Hermoso genuinely misbehaves — a tool errors unexpectedly, returns a wrong or malformed result, a render comes back broken, or documented behaviour doesn't match what happened. Include what you were trying to do, the exact tool call and arguments, and what came back. Do NOT use it for out-of-credits, a policy refusal, or a missing capability (use request_feature for that). Free, no credits.

  mcp-tool

  123456789101112131415161718192021222324252627

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "summary",
      "details"
    ],
    "properties": {
      "details": {
        "type": "string",
        "description": "what you were doing, the tool + arguments you called, what you expected, and what actually happened (paste the exact error)"
      },
      "summary": {
        "type": "string",
        "description": "one-line summary of the bug"
      },
      "severity": {
        "enum": [
          "low",
          "medium",
          "high"
        ],
        "type": "string",
        "description": "high = blocks the task or loses paid work; medium = wrong output but workable; low = cosmetic"
      }
    }
  }

  arguments 27 lines copy
• request_feature unknown never probed

  Ask the Hermoso team for a capability that doesn't exist yet. Use this when you need something Hermoso genuinely can't do — an unsupported platform or channel, a missing model, an export format, a tool that would have completed the user's task but isn't available. Say what the user was trying to achieve, not just the feature name — the use case is what gets built. Free, no credits.

  mcp-tool

  123456789101112131415161718

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "summary",
      "details"
    ],
    "properties": {
      "details": {
        "type": "string",
        "description": "what the user was actually trying to achieve, why the current tools couldn't do it, and what you'd expect the capability to do"
      },
      "summary": {
        "type": "string",
        "description": "one line: the capability you need"
      }
    }
  }

  arguments 18 lines copy
• billing_status unknown never probed

  Show this account's billing at a glance: current plan (id + label + the price it is ACTUALLY billed — quote plan.priceUsd per plan.period, not plan.monthlyUsd), credit balance, whether auto-reload is on, whether a card is on file, and whether YOU (this key) have ADMIN rights to change billing. Read-only, free. Call it before upgrade_plan / set_auto_reload to know what's possible — members have read-only billing. IN A SHARED TEAM WORKSPACE A MEMBER SEES THE PLAN AND THE BALANCE ONLY: the workspace owner's payment card and auto-reload belong to them and are not reported (billingScope:'member'). Never tell a member there is no card on file — the honest answer is that you cannot see it.

  mcp-tool

  12345

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {}
  }

  arguments 5 lines copy
• upgrade_plan unknown never probed

  Change this account's SUBSCRIPTION plan (admin only). Call with no argument to list the plans (id · monthly price · monthly credits); call again with `plan` set to a plan id. A NEW subscriber gets a ready-to-pay Stripe Checkout URL to hand your human — THEY pay on Stripe (agents never spend money directly). If the account already has a paid plan, or you're DOWNGRADING, the change is made by a person in the app (Settings → Billing) and the tool returns exactly what to do. Members (read-only billing) get an honest 'ask an admin' message. Nothing is charged until your human pays.

  mcp-tool

  123456789101112131415161718

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "plan": {
        "type": "string",
        "description": "the plan id to move to (e.g. pro) — omit to list the available plans first"
      },
      "period": {
        "enum": [
          "mo",
          "yr"
        ],
        "type": "string",
        "description": "billing cadence — monthly (default) or yearly (2 months free)"
      }
    }
  }

  arguments 18 lines copy
• set_auto_reload unknown never probed

  Turn automatic credit reloads on or off (admin only): when the balance drops below a threshold, the card on file is charged for a top-up pack — SERVER-SIDE, even with no app open. Requires a saved card, added once in the app at first checkout/top-up; if there's none the tool tells you exactly where to add it. After that one-time card setup, agents can manage auto-reload, top-ups and plan links fully. Members (read-only billing) get an 'ask an admin' message.

  mcp-tool

  12345678910111213141516171819202122232425

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "enabled"
    ],
    "properties": {
      "enabled": {
        "type": "boolean",
        "description": "true to turn auto-reload on, false to turn it off"
      },
      "reloadCredits": {
        "type": "integer",
        "maximum": 9007199254740991,
        "minimum": -9007199254740991,
        "description": "how many credits to add each reload — must match a credit pack size (see buy_credits)"
      },
      "thresholdCredits": {
        "type": "integer",
        "maximum": 9007199254740991,
        "minimum": -9007199254740991,
        "description": "reload when the balance drops below this many credits"
      }
    }
  }

  arguments 25 lines copy
• list_brands unknown never probed

  List every brand on this account (id + name) and which one this connection currently acts on, PLUS any brand another account shared with you (a team workspace). Multi-brand accounts: call this, then use_brand to switch. A SHARED workspace is switched into the SAME way — pass its name or the profile id printed here to use_brand. If a brand looks empty (no connected accounts, no Library) when the app shows it full, you are almost certainly acting on a different workspace: call this first. Read-only, free.

  mcp-tool

  12345

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {}
  }

  arguments 5 lines copy
• use_brand unknown never probed

  Pin which brand this connection acts on (multi-brand accounts). Pass the brand id or exact name from list_brands. Works for a brand on your own account AND for a workspace another account SHARED with you — for a shared one pass its name or the profile id list_brands prints, and access is verified against your real membership before it is pinned. Persists for this API key until changed, on every surface (hosted connector included — no environment variables, no restart).

  mcp-tool

  12345678910111213

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "brand"
    ],
    "properties": {
      "brand": {
        "type": "string",
        "description": "brand id (e.g. default / p_xxx), its exact name from list_brands, or the profile id of a workspace shared with you"
      }
    }
  }

  arguments 13 lines copy
• create_brand unknown never probed

  Add a NEW brand workspace (a separate brand/client on this account) and switch to it. Each workspace has its OWN brand profile, memory, swipefile, Library, avatars, skills, playbooks and connectors — nothing leaks between them. Use this for a second brand or a new client; use draft_brand to FILL a workspace, and update_brand to edit one. Re-running with the same name returns the existing workspace instead of a duplicate. Free (the ~50-credit research cascade only starts when you then run draft_brand).

  mcp-tool

  1234567891011121314151617

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "name"
    ],
    "properties": {
      "name": {
        "type": "string",
        "description": "the brand / client name for the new workspace"
      },
      "activate": {
        "type": "boolean",
        "description": "switch this connection to the new brand (default true) — everything you do next scopes to it"
      }
    }
  }

  arguments 17 lines copy
• delete_brand unknown never probed

  PERMANENTLY delete a brand workspace and EVERYTHING in it — brand profile, memory, swipefile, Library creations, generated assets, avatars, skills, playbooks, chats — and disconnect its connected accounts. Irreversible, and it applies to everyone the workspace is shared with. Call it WITHOUT confirm first: it reports exactly what that workspace holds. Show the user that inventory verbatim, get an unambiguous yes, then call again with confirm:true — plus, if the workspace is not empty, confirmName set to its exact name and confirmConnectors set to the number of connected accounts it reported. Those two exist because confirming INTENT does not prove you picked the right WORKSPACE, and a wrong target is how a live brand was destroyed. The account's FIRST/anchor brand cannot be deleted this way (it holds the workspace's root storage) — that one is replaced from the app.

  mcp-tool

  12345678910111213141516171819202122232425

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "brand"
    ],
    "properties": {
      "brand": {
        "type": "string",
        "description": "brand id or exact name from list_brands"
      },
      "confirm": {
        "type": "boolean",
        "description": "REQUIRED true — this destroys the whole workspace and cannot be undone"
      },
      "confirmName": {
        "type": "string",
        "description": "the workspace's EXACT name, required when it is not empty — copy it from the inventory this tool returned, after the user has agreed to it"
      },
      "confirmConnectors": {
        "type": "number",
        "description": "the number of connected accounts the inventory reported, required when there is at least one — the user must specifically agree to losing them, because reconnecting each needs a browser and no agent can do it"
      }
    }
  }

  arguments 25 lines copy
• list_meta_pages unknown never probed

  List the Facebook Pages (with any linked Instagram business account) and ad accounts on the connected Meta account — use before post_to_meta / create_meta_campaign to pick the target. Requires the user to have connected Meta (Settings ▸ Connectors ▸ Meta); returns a connect hint if not.

  mcp-tool

  12345

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {}
  }

  arguments 5 lines copy
• upload_file unknown never probed

  Persist an ARBITRARY user file (image, video, audio, PDF or document, up to 150MB) into Hermoso and get back a durable public URL that EVERY publish, schedule and ad-build tool accepts — post_to_meta / post_to_linkedin / post_to_linkedin_page / post_to_youtube / post_to_tiktok / post_to_pinterest / post_to_x / post_to_google_business / schedule_post / upload_meta_asset / upload_google_ads_asset / create_meta_ad / create_linkedin_ads_creative / set_youtube_thumbnail / save_to_drive / save_to_onedrive. THIS IS THE BRING-YOUR-OWN-CREATIVE PATH: it is for files that have NOTHING to do with a Hermoso render (media on the user's desktop, an agency's finished ad, a photo they shot), and it means you can publish, schedule and run ads through Hermoso without generating anything here. Provide exactly ONE source — passing two is an error, never a silent preference: `url` (ANY public http(s) link — Hermoso fetches it server-side, so nothing crosses this connection and there is no practical size limit; THIS IS THE ONE THAT ALWAYS WORKS, including on the hosted connector), `dataUri` (a base64 data: URI — keep it under ~15MB, since the bytes travel over this connection). If the file is already at a public https URL, the Meta, Reddit and ChatGPT-Ads tools take it directly and re-host it safely — but LinkedIn (posts and ad creatives), Pinterest, the YouTube thumbnail and upload_google_ads_asset upload the BYTES themselves and therefore refuse an external host, so run it through here first and pass the URL this returns. When in doubt, use this: its URL works everywhere. (Calling the underlying HTTP route directly? POST /api/upload takes the file's RAW BYTES as the request body with its own content-type — NOT multipart/form-data — or ?url=<link> with no body.) Returns {url, kind, bytes}.

  mcp-tool

  12345678910111213141516171819202122

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "url": {
        "type": "string",
        "description": "a PUBLIC http(s) URL Hermoso fetches server-side (private/internal addresses are refused, and every redirect hop is re-checked). Works on every surface including the hosted connector, and the bytes never cross this connection — prefer this whenever the file is reachable on the web."
      },
      "name": {
        "type": "string",
        "description": "original file name — helps pick the right extension"
      },
      "dataUri": {
        "type": "string",
        "description": "base64 data: URI of the file bytes (data:<mime>;base64,<…>) — bytes travel over this connection, so keep it small"
      },
      "getUploadUrl": {
        "type": "boolean",
        "description": "ASK FOR A ONE-TIME UPLOAD URL instead of uploading now — use this whenever the file is on the user’s machine and you can run a shell or an HTTP request. Returns a uploadUrl you PUT the raw bytes to (any HTTP client), which answers with the durable Hermoso url. It beats `dataUri` for anything but a small image: a data: URI spends the whole file as tokens in this conversation. One file per url, and it expires."
      }
    }
  }

  arguments 22 lines copy
• list_whatsapp_accounts unknown never probed

  The WhatsApp Business Accounts SHARED WITH THIS BRAND and the phone numbers registered on each — the ids every other WhatsApp tool needs, plus each number’s QUALITY RATING, which is what decides how many messages Meta will let it send. Start here. A WABA with no number cannot send anything and the reply says so: Hermoso does not register or verify numbers, that is WhatsApp Manager. A business portfolio that could not be read is REPORTED rather than dropped — an account missing from this list would read as "the brand has no WhatsApp", which is a claim about their business and not about our read. TWO ACCOUNTS CAN CARRY THE SAME DISPLAY NAME — always quote the `display` field or the id when naming one to a user, never the bare name. ONLY THE ACCOUNTS SHARED WITH THIS BRAND ARE REACHABLE. One Meta login often administers WhatsApp for several businesses, so a human ticks which belong to this brand under Settings ▸ Connectors ▸ Meta ▸ Manage accounts (or set_connector_accounts(provider:"meta")); nothing else here can see or touch the rest. With none ticked every WhatsApp tool refuses and names that as the way out. With exactly ONE ticked, wabaId is optional — pass it only to disambiguate. Read-only, 0 credits (WhatsApp conversations are billed by META to the business directly, never in Hermoso credits). Needs Meta connected.

  mcp-tool

  12345

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {}
  }

  arguments 5 lines copy
• post_to_meta unknown never probed

  Publish to a connected Facebook Page, its linked Instagram, OR the brand’s Threads account — text/link/image/VIDEO/CAROUSEL. A MULTI-SLIDE creative is a CAROUSEL, not several posts: pass the slides in order as imageUrls[] and they publish as ONE swipeable post (Instagram album, Threads carousel, Facebook multi-photo post). Never publish slide 1 of a deck on its own — the creative tells the viewer to swipe. target:"facebook" (default) posts to the Page; target:"instagram" publishes a photo or Reel to the linked IG business account (needs an image or video); target:"threads" posts to the connected Threads account (text, image, or video). Works with ANY media — a finished Hermoso ad OR an arbitrary user file: imageUrl/videoUrl accept a public https URL, a data: URI, or a Hermoso /generated path; for a LOCAL file (e.g. on the user’s desktop) call upload_file first and pass the url it returns. INSTAGRAM COLLAB: pass `collaborators` (up to 3 usernames) to invite other accounts to CO-AUTHOR the post — it then shows on their profile too once they accept, which is the reach play behind every creator partnership. This PUBLISHES immediately — confirm the copy + media with the user first. Needs a connected Meta account (Settings ▸ Connectors ▸ Meta) with posting permission; Threads needs its own connection.

  mcp-tool

  123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "hook": {
        "type": "string",
        "description": "WHAT ANGLE THIS POST IS BUILT ON — the single most valuable field here, and the only moment it can ever be recorded. post_performance groups on it to answer \"which hooks work\", and it needs 5 posts sharing ONE hook before it will call anything a winner, so REUSE THE SAME WORDING across a campaign instead of rephrasing it every time. Best of all, pass a hook id from list_hooks (e.g. \"direct_callout\", \"mid_problem\", \"before_after\") — those fold onto a stable key however they are spelled, so a whole brand accumulates evidence on one row. Your own wording is fine too; it just only groups when you repeat it exactly. Omitting it means this post can never vote on which hook works."
      },
      "link": {
        "type": "string",
        "description": "a URL to attach (FB text post only)"
      },
      "async": {
        "type": "boolean",
        "description": "publish in the BACKGROUND and return a job id to poll with get_job, instead of waiting. USE THIS FOR VIDEO: a Facebook or Instagram video publish routinely outlives an agent transport, and a timeout on the synchronous path leaves you unable to tell whether the post is live. With async:true nothing can time out — the job reports the post id and url when it lands."
      },
      "brand": {
        "type": "string",
        "description": "WHICH BRAND this post belongs to — the id or exact name from list_brands (a workspace shared with you: its profile id). Use it whenever the account has more than one brand and you are not certain which one this connection is pinned to: it beats the pin for THIS CALL ONLY and changes nothing about the connection. A name that matches no brand, or two brands, is REFUSED and nothing is posted — never resolved to the pin, which is the account you were guarding against."
      },
      "place": {
        "type": "string",
        "description": "FACEBOOK — tag a location on the Page post. The NUMERIC ID OF THE FACEBOOK PAGE for that place, not a place name and not coordinates."
      },
      "story": {
        "type": "boolean",
        "description": "INSTAGRAM STORY — publish this as a 24-hour Story instead of a feed post. One image OR one video: Instagram has no carousel story, so a carousel is REFUSED BY NAME rather than quietly posted to the feed. A Story carries NO CAPTION (there is nowhere to show one), no collaborators, no product tags and no trialReel — passing any of those is refused by name and nothing is posted, because a story that silently drops the words is worse than one that never went. INSTAGRAM ONLY: a Facebook Page story is a different upload and is not built, so a Facebook channel with `story` set is refused rather than published to the feed."
      },
      "pageId": {
        "type": "string",
        "description": "target Page id (from list_meta_pages); omit = first Page"
      },
      "target": {
        "enum": [
          "facebook",
          "instagram",
          "threads"
        ],
        "type": "string",
        "description": "default facebook; instagram → the Page’s linked IG; threads → the brand’s connected Threads account"
      },
      "account": {
        "type": "string",
        "description": "WHICH Instagram account when target is instagram and the brand has several — Page-linked and Instagram Login accounts alike; an @username or id from list_connector_accounts(\"instagram\"). Several and none named is refused by name; omit when there is one."
      },
      "altText": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        ],
        "description": "ACCESSIBILITY — the description screen readers announce, and what the platform otherwise auto-generates badly or not at all. Describe what is actually IN the picture, never the caption. ONE STRING describes the picture; on a CAROUSEL it describes EVERY slide. Pass an ARRAY of strings instead to describe each slide separately, aligned to the slide order — that is strictly better on a multi-slide post, because one sentence read out over six different pictures is wrong for five of them. More descriptions than pictures is refused rather than dropped. WHERE IT LANDS, per Meta’s own docs: INSTAGRAM image posts and the IMAGE slides of an Instagram carousel (up to 1000 characters; dropped rather than sent on a Reel or a video slide, which Meta do not support); FACEBOOK Page photos including every photo of an album, via alt_text_custom (Meta publish no length for it, so nothing is truncated); THREADS on a single-image or single-video post ONLY — Meta document no way to attach alt text to a Threads CAROUSEL slide, so a Threads carousel publishes undescribed and the reply says so rather than risking the whole post on a guess. (Meta’s AI disclosure defaults from PROVENANCE: a Hermoso render is declared is_ai_generated; media that came through upload_file or an external URL, i.e. the user’s own photos or footage, is NOT. Pass `aiGenerated` to force it either way.)"
      },
      "message": {
        "type": "string",
        "description": "post text / caption"
      },
      "subject": {
        "type": "string",
        "description": "WHAT THIS POST IS ABOUT — the product, feature, offer or theme (e.g. \"winter coat\", \"free trial\", \"founder story\"). The second grouping axis in post_performance. Same rule as hook: reuse the exact wording so posts about one subject land in one group."
      },
      "audience": {
        "type": "object",
        "properties": {
          "cities": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Meta location keys for cities"
          },
          "minAge": {
            "anyOf": [
              {
                "type": "number",
                "const": 13
              },
              {
                "type": "number",
                "const": 15
              },
              {
                "type": "number",
                "const": 18
              },
              {
                "type": "number",
                "const": 21
              },
              {
                "type": "number",
                "const": 25
              }
            ]
          },
          "regions": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Meta location keys for regions/states"
          },
          "countries": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "two-letter codes, e.g. [\"CA\",\"US\"]"
          }
        },
        "description": "FACEBOOK PAGE POST ONLY — limit who can see this organic post to people in these places and/or over this age (Facebook allows 13, 15, 18, 21 or 25). Not on Instagram, Threads or a Facebook Reel (a vertical clip becomes a Reel): those are refused. Region and city keys come from the Meta ads location search."
      },
      "coverUrl": {
        "type": "string",
        "description": "INSTAGRAM REEL COVER — a public image url Instagram fetches and uses as the cover in the Reels tab. REELS ONLY, and the alternative to `thumbOffset`: passing both is refused, since they are two answers to the same question. Run a local file through upload_file first."
      },
      "imageUrl": {
        "type": "string",
        "description": "public https URL, a data: URI, or a Hermoso /generated path (upload_file gives you one for a local file)"
      },
      "linkName": {
        "type": "string",
        "description": "FACEBOOK — override the HEADLINE of the link preview. Without it the post shows whatever Open Graph title the destination carries, which on a bare landing page is often nothing. Needs `link`. MEASURED 2026-09-17: Facebook only honours these when the Page’s business has VERIFIED the domain (Business Manager ▸ Brand safety ▸ Domains) — without that Meta refuses the post outright with “Only owners of the URL…”, so leave them out unless the brand owns and has verified that link’s domain."
      },
      "topicTag": {
        "type": "string",
        "description": "THREADS ONLY — one topic tag for discovery, 1–50 characters. A leading # is stripped for you; Threads refuses \".\" and \"&\"."
      },
      "videoUrl": {
        "type": "string",
        "description": "public https URL, data: URI, or /generated path — FB video post / IG Reel"
      },
      "audioName": {
        "type": "string",
        "description": "INSTAGRAM REEL — the name of the Reel’s audio track, which is what viewers tap through to. REELS ONLY."
      },
      "imageUrls": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "CAROUSEL — an ORDERED list of image (and, where the channel allows, video) URLs published as ONE post the viewer swipes through. THIS IS NOT “post several” — it is a single post with several slides, which is what a multi-slide creative (a listicle, a “1/6 · SWIPE” deck) actually needs; publishing only its first slide tells the viewer to swipe at something that cannot. The ORDER is the product. Limits per channel: Instagram 2–10 (images, videos or a mix), Threads 2–20 (mix allowed), Facebook 2+ (Meta publishes no documented maximum; Hermoso caps the upload fan-out at 30 and says so), LinkedIn company Pages 2–20 (images only), Pinterest 2–5 (images only), TikTok up to 35. One url here is simply an ordinary single post. Anything a channel cannot do is REFUSED with the real reason — nothing is ever quietly downgraded to one slide."
      },
      "trialReel": {
        "enum": [
          "MANUAL",
          "SS_PERFORMANCE"
        ],
        "type": "string",
        "description": "INSTAGRAM TRIAL REEL — publish this Reel to NON-FOLLOWERS ONLY at first (Instagram allows trials only on accounts above its follower threshold — about 1,000 followers; an ineligible account is refused by name and nothing is posted), so a hook can be tested on a cold audience without spending it on the people who already follow the brand. Instagram then shows it to followers only if it graduates. MANUAL = the creator graduates it by hand in the Instagram app; SS_PERFORMANCE = Instagram graduates it automatically if it performs well. REELS ONLY and INSTAGRAM ONLY: an image, a carousel, a Facebook post or a Threads post is REFUSED BY NAME rather than quietly published as an ordinary post — a trial that silently goes to every follower is the exact opposite of what was asked for. Omit it for a normal Reel."
      },
      "locationId": {
        "type": "string",
        "description": "TAG A PLACE. THREADS: a place id from search_threads_locations. INSTAGRAM: the NUMERIC ID OF A FACEBOOK PAGE associated with that location, not a place name and not coordinates; a non-numeric value is refused rather than sent."
      },
      "scheduleAt": {
        "type": "string",
        "description": "FACEBOOK ONLY — schedule instead of posting now. ISO timestamp (2026-08-01T09:00:00Z) or unix seconds; must be 10 minutes to 30 days ahead. Facebook holds the post and publishes it at that time, so nothing has to stay running on our side. Instagram and Threads have NO scheduling in Meta’s API — passing this for them is refused rather than silently posted immediately."
      },
      "aiGenerated": {
        "type": "boolean",
        "description": "INSTAGRAM / FACEBOOK REEL — Meta’s is_ai_generated self-disclosure. OMIT IT and Hermoso decides from provenance: a Hermoso render is declared, media that came through upload_file or from an external URL (the user’s own photographs or footage) is NOT — a real photo must never carry Instagram’s “AI info” label. Pass true or false only to override: false strips the label from something Hermoso would otherwise declare, true declares a render the user uploaded themselves."
      },
      "linkPicture": {
        "type": "string",
        "description": "FACEBOOK — override the IMAGE of the link preview: a public http(s) url Facebook fetches itself. Needs `link`. MEASURED 2026-09-17: Facebook only honours these when the Page’s business has VERIFIED the domain (Business Manager ▸ Brand safety ▸ Domains) — without that Meta refuses the post outright with “Only owners of the URL…”, so leave them out unless the brand owns and has verified that link’s domain."
      },
      "productTags": {
        "type": "array",
        "items": {},
        "description": "INSTAGRAM SHOPPING — make the post SHOPPABLE by tagging products from the brand’s own catalog; tapping a tag opens the product’s price sheet inside Instagram. Instagram only. ON A PHOTO each tag is {product_id, x, y}, where x and y are FRACTIONS of the image from 0.0 (left/top) to 1.0 (right/bottom) — 0.5,0.5 is the middle — and BOTH are required, max 20. ON A REEL it is {product_id} ALONE with no coordinates, max 30. ON A CAROUSEL it is an array PER SLIDE ([[{…}], [], [{…}]]) because Instagram tags each slide’s own container, max 5 per slide and 20 across the post. Ids come from search_instagram_shopping_products; call list_instagram_shopping_catalogs FIRST, because tagging needs an APPROVED Instagram Shop and without one this fails after the media is already uploaded. A tag whose product is not “approved” is stored and shown to nobody."
      },
      "quotePostId": {
        "type": "string",
        "description": "THREADS ONLY — the id of a post to QUOTE. A quote post is a distinct post type, not a formatting option."
      },
      "shareToFeed": {
        "type": "boolean",
        "description": "INSTAGRAM REEL — true puts the Reel in the Feed grid as well as the Reels tab. REELS ONLY. Left unset it follows Instagram’s own default; Hermoso does not flip it either way on the user’s behalf."
      },
      "thumbOffset": {
        "type": "number",
        "description": "INSTAGRAM REEL COVER, the other way — which frame becomes the cover, in MILLISECONDS from the start of the video. REELS ONLY. Use it instead of `coverUrl` when the right cover is already a frame of the clip."
      },
      "callToAction": {
        "enum": [
          "BOOK_TRAVEL",
          "BUY_NOW",
          "CALL_NOW",
          "DOWNLOAD",
          "GET_DIRECTIONS",
          "LEARN_MORE",
          "LIKE_PAGE",
          "MESSAGE_PAGE",
          "NO_BUTTON",
          "OPEN_LINK",
          "SHOP_NOW",
          "SIGN_UP",
          "WATCH_MORE"
        ],
        "type": "string",
        "description": "FACEBOOK — a real call-to-action BUTTON on the Page post. The types that open a destination (SHOP_NOW, LEARN_MORE, SIGN_UP, BUY_NOW, DOWNLOAD, OPEN_LINK, WATCH_MORE, BOOK_TRAVEL) need somewhere to go: the post’s own `link`, or `callToActionLink`. CALL_NOW, MESSAGE_PAGE, LIKE_PAGE and GET_DIRECTIONS act on the Page itself and take none."
      },
      "countryCodes": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "THREADS ONLY — restrict the post to these ISO 3166-1 alpha-2 countries. ⚠ This is an ALLOWLIST, so the post becomes INVISIBLE in every country not named — it narrows reach, it does not target."
      },
      "replyControl": {
        "enum": [
          "everyone",
          "accounts_you_follow",
          "mentioned_only",
          "parent_post_author_only",
          "followers_only"
        ],
        "type": "string",
        "description": "THREADS ONLY — who may reply. Default is everyone."
      },
      "collaborators": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "INSTAGRAM COLLAB — up to 3 Instagram usernames invited to CO-AUTHOR this post. Once one accepts, the post appears on THEIR profile too, with both handles in the header and the likes and comments shared — it is how a brand reaches a creator’s audience without paying for placement, and it is the single most-asked thing a scheduler normally cannot do. Pass handles only (\"hermosoai\"), not profile links; a leading @ is fine. INSTAGRAM ONLY — Facebook and Threads have no collab post at all and are refused BY NAME rather than silently dropping the co-authors — and never on a Story. AN INVITE IS NOT A CO-POST: publishing SENDS a request the other account must accept in their Instagram notifications, and until they do the post is on this brand’s profile ALONE; they may also decline, and Instagram sends no notification either way. So never report the post as live on both accounts — read the invite status back out of the reply, and use instagram_collaborators later to find out whether they accepted."
      },
      "platformCover": {
        "type": "boolean",
        "description": "VIDEO COVER. Omit it (the default) and Hermoso sets the video’s best frame — the same frame as its Library thumbnail — as the cover (Instagram Reel: thumb_offset; Facebook video/Reel: an uploaded cover image) — and on Threads, which has no cover setting, a blank first frame is replaced on a copy sent to Threads only. true = send no cover and let the platform pick (usually the first frame). A cover you pass yourself always wins."
      },
      "allowDuplicate": {
        "type": "boolean",
        "description": "post it even though an identical post was just made or attempted. Only pass this when the user genuinely wants the same thing posted twice, or when you have LOOKED at the account and confirmed a timed-out attempt did not land."
      },
      "idempotencyKey": {
        "type": "string",
        "description": "SAFE RETRIES. Publishing can take minutes (a video upload, a carousel of ten slides) and a transport can time out while the post SUCCEEDS — retrying blind is how the same thing gets posted twice. Pass any stable string here and a repeat of the SAME publish returns the ORIGINAL post id instead of posting again (24h). You do not have to: an identical publish is auto-recognised for 10 minutes anyway. If a call times out or errors ambiguously, CALL AGAIN WITH THE SAME KEY — that is the safe move, and it will either report the original post or publish it for the first time. It never posts twice."
      },
      "linkAttachment": {
        "type": "string",
        "description": "THREADS TEXT POSTS ONLY — a full http(s) URL rendered as a clickable link card. This is how a Threads post carries a destination at all; without it a link is just text. Meta allows at most 5 links per post and refuses a link attachment on a post that also carries an image or video, so Hermoso refuses that combination up front rather than letting Meta silently drop it."
      },
      "linkDescription": {
        "type": "string",
        "description": "FACEBOOK — override the DESCRIPTION of the link preview. Needs `link`. MEASURED 2026-09-17: Facebook only honours these when the Page’s business has VERIFIED the domain (Business Manager ▸ Brand safety ▸ Domains) — without that Meta refuses the post outright with “Only owners of the URL…”, so leave them out unless the brand owns and has verified that link’s domain."
      },
      "paidPartnership": {
        "type": "boolean",
        "description": "INSTAGRAM — the PAID PARTNERSHIP label. A COMPLIANCE DECLARATION, the same kind Hermoso already carries for TikTok and X: set it whenever the post is sponsored, gifted or otherwise paid for. Opt-in and never inferred — it is the poster’s own statement about their commercial relationship."
      },
      "callToActionLink": {
        "type": "string",
        "description": "FACEBOOK — where the button goes, when that is not the post’s own `link`."
      },
      "crossreshareToIg": {
        "type": "boolean",
        "description": "THREADS ONLY — ALSO share this Threads post to the linked Instagram account AS A STORY (not a feed post), in the same publish. NOT available on a Threads CAROUSEL, which is refused by name rather than silently dropped. THERE IS NO CONFIRMATION: Threads returns no field saying whether the Story was created, so report it as REQUESTED and tell the user to check their Instagram Stories — never that it is live."
      },
      "crossreshareDarkMode": {
        "type": "boolean",
        "description": "THREADS ONLY — render that Instagram Story in dark mode. Only meaningful alongside crossreshareToIg; on its own it is refused rather than silently ignored, because a parameter that never reaches the wire must not look accepted."
      },
      "brandedContentSponsorIds": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "INSTAGRAM — the numeric Instagram USER IDS of the brands behind that label (at most 2, and ids rather than @handles). Naming sponsors IS asking for the label, so setting these with `paidPartnership:false` is refused instead of publishing brand credits with no disclosure."
      }
    }
  }

  arguments 279 lines copy
• schedule_post unknown never probed

  Queue a post to go out at a future time, to one or more connected channels at once (facebook, instagram, threads, tiktok, youtube, linkedin, x, pinterest, bluesky, telegram — TEN channels, and every one of them is live. google_business is accepted by the schema too but is currently HELD BACK: Google allowlists that API per project and ours reads 0 QPM, so it is refused at enqueue rather than failing hours later). A MULTI-SLIDE creative goes in imageUrls[] as a CAROUSEL, in order — never schedule just its first slide. Either name the exact time in `at`, or pass `useQueue:true` to take the brand’s next free POSTING SLOT (its saved posting times, skipping any already occupied) — that is what “just queue it” means and it saves the user picking a minute. Pass a Hermoso render URL as imageUrl/videoUrl (or an upload_file URL for external media). PINTEREST AND YOUTUBE ALSO SHOW A TITLE: pass `title` (max 100 chars) — omit it and Hermoso derives one from the caption’s first sentence rather than truncating the caption mid-word. YOUTUBE: `description` (≤5000 chars) is the box under the video for the links and CTA, and the caption stands in when it is omitted; `tags` up to 30; `thumbnailUrl` sets the custom thumbnail. Use `captions` to give each channel its own wording; anything not listed falls back to `message`. PER-CHANNEL SETTINGS, all carried straight through to the real publisher: TIKTOK takes the paid-partnership disclosure (`brandedContent`) and the own-brand one (`yourBrand`) — set them whenever the post is commercial, they are compliance declarations — plus `disableComment` and, on a video, `disableDuet` / `disableStitch` / `coverTimestampMs`. GOOGLE BUSINESS takes `topicType` (STANDARD / EVENT / OFFER / ALERT) with `event` and `offer`, and a real `actionType` button instead of the hard-coded Learn more. X takes a whole `thread`, a `poll`, `replySettings` and `madeWithAi`. INSTAGRAM takes `collaborators` — up to 3 usernames invited to CO-AUTHOR the post, which puts it on their profile too once they accept (the invite is sent when the post fires, and is pending until then). Channels are attempted INDEPENDENTLY, so one failing channel never blocks the others. SOME CHANNELS MUST BE TOLD WHICH ACCOUNT, and Hermoso never guesses one: a Pinterest pin needs `boardId` (list_pinterest_boards) or it is refused outright; a LinkedIn COMPANY PAGE post needs `linkedinOrganizationId` (list_linkedin_pages) and without it the post goes to the connected person’s own profile; a brand with more than one connected Facebook Page needs `pageId` (list_meta_pages) and an account managing more than one Google Business listing needs `locationId` (list_business_locations) — resolve those FIRST and let the user pick, because with several to choose from and no id the post is refused when it fires, hours later. A scheduled post GOES LIVE PUBLICLY by default on every channel — that is what scheduling means, and nothing is ever quietly downgraded to a draft or an unlisted upload. If the user genuinely wants something staged instead, set `visibility` (or `visibilityByChannel` for just one channel): ‘public’ (default, live) · ‘unlisted’ (YouTube only — link-only) · ‘private’ (YouTube private, or TikTok posted SELF_ONLY) · ‘draft’ (TikTok drafts, or an unpublished Facebook Page post for a human to publish). Ask for a weaker visibility only if the user asked for one. If a channel cannot do the visibility requested, the call is REFUSED right now with the reason, rather than posting something weaker later. Most channels publish publicly and nothing else: only YouTube has unlisted/private, only TikTok has private/draft, and only Facebook has draft.

  mcp-tool

  123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "channels"
    ],
    "properties": {
      "at": {
        "type": "string",
        "description": "when to post — ISO timestamp (2026-08-01T09:00:00Z) or epoch milliseconds. Must be in the future, at most 365 days out. Give this OR useQueue, never both."
      },
      "hook": {
        "type": "string",
        "description": "WHAT ANGLE THIS POST IS BUILT ON — the single most valuable field here, and the only moment it can ever be recorded. post_performance groups on it to answer \"which hooks work\", and it needs 5 posts sharing ONE hook before it will call anything a winner, so REUSE THE SAME WORDING across a campaign instead of rephrasing it every time. Best of all, pass a hook id from list_hooks (e.g. \"direct_callout\", \"mid_problem\", \"before_after\") — those fold onto a stable key however they are spelled, so a whole brand accumulates evidence on one row. Your own wording is fine too; it just only groups when you repeat it exactly. Omitting it means this post can never vote on which hook works."
      },
      "link": {
        "type": "string",
        "description": "a link to attach (Facebook)"
      },
      "poll": {
        "type": "object",
        "required": [
          "options"
        ],
        "properties": {
          "options": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "durationMinutes": {
            "type": "number"
          }
        },
        "description": "X — attach a poll: {options:[\"…\",\"…\"], durationMinutes}. 2–4 options of at most 25 characters each; voting runs 5–10080 minutes (7 days), default 1440. X makes a poll MUTUALLY EXCLUSIVE with media, so an item carrying an image or video is refused — schedule the poll as its own X-only post."
      },
      "tags": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "YOUTUBE — up to 30 search tags for the video (plain words, no #)."
      },
      "brand": {
        "type": "string",
        "description": "WHICH BRAND this post belongs to — the id or exact name from list_brands (a workspace shared with you: its profile id). Use it whenever the account has more than one brand and you are not certain which one this connection is pinned to: it beats the pin for THIS CALL ONLY and changes nothing about the connection. A name that matches no brand, or two brands, is REFUSED and nothing is posted — never resolved to the pin, which is the account you were guarding against."
      },
      "event": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string"
          },
          "endDate": {
            "type": "string"
          },
          "endTime": {
            "type": "string"
          },
          "startDate": {
            "type": "string"
          },
          "startTime": {
            "type": "string"
          }
        },
        "description": "GOOGLE BUSINESS — required for an EVENT or OFFER post: {title, startDate:\"YYYY-MM-DD\", endDate, startTime:\"HH:MM\", endTime}. `title` is the EVENT’s headline, a different thing from the post `title` (which is the Pinterest/YouTube one). Google documents its TimeInterval as needing all four date/time parts to be valid, so send the times whenever you know them."
      },
      "offer": {
        "type": "object",
        "properties": {
          "couponCode": {
            "type": "string"
          },
          "redeemOnlineUrl": {
            "type": "string"
          },
          "termsConditions": {
            "type": "string"
          }
        },
        "description": "GOOGLE BUSINESS — OFFER posts only: {couponCode, redeemOnlineUrl, termsConditions}. redeemOnlineUrl is where an offer actually sends people, since the button link is ignored on an Offer."
      },
      "place": {
        "type": "string",
        "description": "FACEBOOK — tag a location on the Page post. The NUMERIC ID OF THE FACEBOOK PAGE for that place, not a place name and not coordinates."
      },
      "story": {
        "type": "boolean",
        "description": "INSTAGRAM STORY — publish this as a 24-hour Story instead of a feed post. One image OR one video: Instagram has no carousel story, so a carousel is REFUSED BY NAME rather than quietly posted to the feed. A Story carries NO CAPTION (there is nowhere to show one), no collaborators, no product tags and no trialReel — passing any of those is refused by name and nothing is posted, because a story that silently drops the words is worse than one that never went. INSTAGRAM ONLY: a Facebook Page story is a different upload and is not built, so a Facebook channel with `story` set is refused rather than published to the feed."
      },
      "title": {
        "type": "string",
        "description": "PINTEREST / YOUTUBE — the headline, max 100 characters. Pinterest shows it in search and under the pin; YouTube requires one. Leave it out and Hermoso derives one from that channel’s caption (first sentence, cut on a word boundary, trailing hashtags dropped) — set a real one whenever the caption does not open with a usable headline."
      },
      "chatId": {
        "type": "string",
        "description": "TELEGRAM — REQUIRED whenever telegram is a channel: WHICH chat, group or channel the bot posts to. A public channel’s @username (@hermosoai) or the numeric id (a group is negative; a supergroup or channel starts with -100). There is no default and there cannot be one — the Telegram Bot API publishes no method that lists a bot’s chats — so scheduling telegram without one is refused up front. list_telegram_chats finds ids for chats that have messaged the bot in the last 24 hours."
      },
      "pageId": {
        "type": "string",
        "description": "FACEBOOK / INSTAGRAM / THREADS — which connected Facebook Page (and its linked Instagram) publishes, from list_meta_pages. Needed when the brand has more than one Page connected; with several and no id the post is refused at fire time rather than sent from the wrong brand."
      },
      "thread": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "X — publish a THREAD, one entry per post, each replying to the one before (at most 25). 280 characters per part without X Premium, up to 25,000 with it; nothing is truncated. It REPLACES the X caption: with a thread set, `message`/`captions.x` is not sent to X at all. A thread cannot carry a poll."
      },
      "altText": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        ],
        "description": "ACCESSIBILITY — the screen-reader description of the attached image. ONE STRING describes the picture; on a CAROUSEL it describes EVERY slide. Pass an ARRAY of strings instead to describe each slide separately, aligned to the slide order — that is strictly better on a multi-slide post, because one sentence read out over six different pictures is wrong for five of them. More descriptions than pictures is refused rather than dropped. Write one whenever the post carries an image: describe what is IN the picture, never a repeat of the caption, which a screen reader already reads. CARRIED BY: X (max 1000, one per media), Pinterest (max 500 — PIN-LEVEL only, since its API has no per-item alt text, so slide 1’s description is used for the whole Pin and the result says the others were not sent), LinkedIn COMPANY PAGES (max 4086, one per slide), INSTAGRAM image posts and image slides (max 1000), FACEBOOK photos and albums, and BLUESKY, whose lexicon makes it REQUIRED on every image. The schedule is REFUSED if the LONGEST description exceeds the tightest of the channels on it, rather than truncated on the way out. NOT CARRIED, and none of these is a refusal — the post still publishes, just undescribed there, and the per-channel result says which: TikTok (its photo post has no alt field at any level), a THREADS CAROUSEL, an INSTAGRAM Reel or video slide, and a LinkedIn PERSONAL-profile post."
      },
      "boardId": {
        "type": "string",
        "description": "PINTEREST — REQUIRED whenever pinterest is a channel: the board the Pin goes on, from list_pinterest_boards. The user picks it; a Pin on the wrong board is a public mistake. Scheduling pinterest without one is refused immediately."
      },
      "message": {
        "type": "string",
        "description": "the caption/text used for every channel unless overridden in captions"
      },
      "subject": {
        "type": "string",
        "description": "WHAT THIS POST IS ABOUT — the product, feature, offer or theme (e.g. \"winter coat\", \"free trial\", \"founder story\"). The second grouping axis in post_performance. Same rule as hook: reuse the exact wording so posts about one subject land in one group."
      },
      "accounts": {
        "type": "object",
        "description": "WHICH accounts of a multi-account channel to post to, e.g. { \"tiktok\": [\"@a\", \"@b\"] } or { \"tiktok\": \"all\" } — one row per account at fire time, each with its own result. Omit for channels with one account (several and none named is refused by name).",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {
          "anyOf": [
            {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            {
              "type": "string",
              "const": "all"
            }
          ]
        }
      },
      "audience": {
        "type": "object",
        "properties": {
          "cities": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Meta location keys for cities"
          },
          "minAge": {
            "anyOf": [
              {
                "type": "number",
                "const": 13
              },
              {
                "type": "number",
                "const": 15
              },
              {
                "type": "number",
                "const": 18
              },
              {
                "type": "number",
                "const": 21
              },
              {
                "type": "number",
                "const": 25
              }
            ]
          },
          "regions": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Meta location keys for regions/states"
          },
          "countries": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "two-letter codes, e.g. [\"CA\",\"US\"]"
          }
        },
        "description": "FACEBOOK PAGE POST ONLY — limit who can see this organic post to people in these places and/or over this age (Facebook allows 13, 15, 18, 21 or 25). Not on Instagram, Threads or a Facebook Reel (a vertical clip becomes a Reel): those are refused. Region and city keys come from the Meta ads location search."
      },
      "captions": {
        "type": "object",
        "description": "per-channel caption overrides, e.g. { \"instagram\": \"…\", \"threads\": \"…\" } — platforms want different lengths and hashtag conventions",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {
          "type": "string"
        }
      },
      "channels": {
        "type": "array",
        "items": {
          "enum": [
            "facebook",
            "instagram",
            "threads",
            "tiktok",
            "youtube",
            "linkedin",
            "x",
            "pinterest",
            "google_business",
            "bluesky",
            "telegram"
          ],
          "type": "string"
        },
        "description": "one or more channels to post to at that time"
      },
      "coverUrl": {
        "type": "string",
        "description": "INSTAGRAM REEL COVER — a public image url Instagram fetches and uses as the cover in the Reels tab. REELS ONLY, and the alternative to `thumbOffset`: passing both is refused, since they are two answers to the same question. Run a local file through upload_file first."
      },
      "imageUrl": {
        "type": "string",
        "description": "a Hermoso render URL (a /generated path, or what upload_file returned), a data: URI, or a public https URL. NOTE: only Facebook/Instagram/Threads accept an arbitrary public URL — X, TikTok, YouTube, LinkedIn, Pinterest and Google Business re-host the bytes and REFUSE anything that is not a Hermoso render, so run an external file through upload_file first and schedule that url."
      },
      "linkName": {
        "type": "string",
        "description": "FACEBOOK — override the HEADLINE of the link preview. Without it the post shows whatever Open Graph title the destination carries, which on a bare landing page is often nothing. Needs `link`. MEASURED 2026-09-17: Facebook only honours these when the Page’s business has VERIFIED the domain (Business Manager ▸ Brand safety ▸ Domains) — without that Meta refuses the post outright with “Only owners of the URL…”, so leave them out unless the brand owns and has verified that link’s domain."
      },
      "timezone": {
        "type": "string",
        "description": "IANA zone for the queue, e.g. \"America/New_York\" — only meaningful with useQueue, and it overrides the brand’s saved zone for this one post. A saved slot of \"09:00\" is a WALL-CLOCK time, so the zone is what turns it into an instant; without either the brand’s saved zone or this, the queue resolves in UTC."
      },
      "topicTag": {
        "type": "string",
        "description": "THREADS ONLY — one topic tag for the post, without the leading #."
      },
      "useQueue": {
        "type": "boolean",
        "description": "instead of naming a minute, drop this into the brand’s POSTING QUEUE: Hermoso takes the earliest of its saved posting times that is still free (skipping any slot another queued post already holds). This is the natural answer to “just queue it” / “post it at my next opening”. Mutually exclusive with `at` — passing both is refused rather than one being silently preferred. If the brand has no posting times set, or every slot for the next 90 days is taken, it is refused by name and nothing is scheduled."
      },
      "videoUrl": {
        "type": "string",
        "description": "a Hermoso render URL (a /generated path, or what upload_file returned), a data: URI, or a public https URL — required for youtube, and for tiktok unless you pass an imageUrl (TikTok takes a photo post too). Same origin rule as imageUrl: everything except Facebook/Instagram/Threads REFUSES a non-Hermoso URL, so pass external video through upload_file first."
      },
      "xArticle": {
        "type": "object",
        "required": [
          "title"
        ],
        "properties": {
          "title": {
            "type": "string"
          },
          "headings": {
            "enum": [
              "blocks",
              "text"
            ],
            "type": "string"
          }
        },
        "description": "X: publish the X item as a long-form X ARTICLE. title is its headline, the X text (message or captions.x) its markdown body, the image its cover. Refused now if the markdown has formatting X cannot hold. X allows about 5 Articles a day; one that fires into that cap fails with the reset time and can be retried."
      },
      "audioName": {
        "type": "string",
        "description": "INSTAGRAM REEL — the name of the Reel’s audio track, which is what viewers tap through to. REELS ONLY."
      },
      "imageUrls": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "CAROUSEL — an ORDERED list of image URLs to publish as ONE swipeable post on every channel that supports it (Instagram 2–10, Threads 2–20, Facebook, LinkedIn company Pages 2–20, Pinterest 2–5, TikTok up to 35 as a photo post). Use this whenever the creative is a multi-slide deck: a scheduled post carrying only slide 1 of a “1/6 · SWIPE” set is a broken ad that nobody is watching when it fires. THE ORDER IS THE PRODUCT. A channel on this schedule that cannot do carousels — X, YouTube, Google Business Profile — is REFUSED NOW, with the reason, so you can drop it or give it its own single image; it is never quietly downgraded hours later."
      },
      "slideText": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "link": {
              "type": "string"
            },
            "title": {
              "type": "string"
            },
            "description": {
              "type": "string"
            }
          }
        },
        "description": "PINTEREST CAROUSEL ONLY — per-slide title / description / link, aligned to slide order. Every other platform takes ONE caption for the whole carousel."
      },
      "topicType": {
        "enum": [
          "STANDARD",
          "EVENT",
          "OFFER",
          "ALERT"
        ],
        "type": "string",
        "description": "GOOGLE BUSINESS — the KIND of Post. STANDARD is the default; EVENT and OFFER both REQUIRE `event` (title + start date), and OFFER also takes `offer`."
      },
      "trialReel": {
        "enum": [
          "MANUAL",
          "SS_PERFORMANCE"
        ],
        "type": "string",
        "description": "INSTAGRAM TRIAL REEL — publish this Reel to NON-FOLLOWERS ONLY at first (Instagram allows trials only on accounts above its follower threshold — about 1,000 followers; an ineligible account is refused by name and nothing is posted), so a hook can be tested on a cold audience without spending it on the people who already follow the brand; Instagram shows it to followers only if it graduates. MANUAL = the creator graduates it by hand in the Instagram app; SS_PERFORMANCE = Instagram graduates it automatically if it performs. REELS ONLY and INSTAGRAM ONLY: an image, a carousel, or a Facebook/Threads channel is REFUSED BY NAME rather than quietly published as an ordinary post — a trial that silently goes to every follower is the exact opposite of what was asked for, so Instagram must be one of the `channels` and the item must carry a video. Omit it for a normal Reel."
      },
      "yourBrand": {
        "type": "boolean",
        "description": "TIKTOK — the OWN-BRAND disclosure (brand_organic_toggle): true when the post promotes the creator’s own business. TikTok asks for at least one of this and brandedContent once a post is commercial."
      },
      "actionType": {
        "enum": [
          "BOOK",
          "ORDER",
          "SHOP",
          "LEARN_MORE",
          "SIGN_UP",
          "CALL"
        ],
        "type": "string",
        "description": "GOOGLE BUSINESS — the call-to-action button. Every button except CALL needs `link` (CALL dials the number on the listing and takes none). Google IGNORES the button link on an OFFER post — put the destination in offer.redeemOnlineUrl. Omit and a post carrying a link gets LEARN_MORE."
      },
      "locationId": {
        "type": "string",
        "description": "GOOGLE BUSINESS PROFILE — which listing, e.g. 'locations/123' from list_business_locations. Needed when the account manages more than one storefront; it is never chosen for the user."
      },
      "madeWithAi": {
        "type": "boolean",
        "description": "X — X’s AI-media label on this post. Opt-in: X treats it as the poster’s own claim about their media, so it is never set on the user’s behalf."
      },
      "visibility": {
        "enum": [
          "public",
          "unlisted",
          "private",
          "draft"
        ],
        "type": "string",
        "description": "how it should be published — DEFAULT 'public' (live). Only pass something else if the user explicitly asked to stage/hide it. Not every channel supports every value; an impossible combination is refused when you schedule it, with the reason."
      },
      "aiGenerated": {
        "type": "boolean",
        "description": "INSTAGRAM / FACEBOOK REEL — Meta’s is_ai_generated self-disclosure. OMIT IT and Hermoso decides from provenance: a Hermoso render is declared, media that came through upload_file or from an external URL (the user’s own photographs or footage) is NOT — a real photo must never carry Instagram’s “AI info” label. Pass true or false only to override: false strips the label from something Hermoso would otherwise declare, true declares a render the user uploaded themselves."
      },
      "communityId": {
        "type": "string",
        "description": "X — publish into an X COMMUNITY instead of the main timeline: the number in the community’s own URL (x.com/i/communities/<id>). The connected account must be a MEMBER of it."
      },
      "description": {
        "type": "string",
        "description": "YOUTUBE: the video DESCRIPTION, max 5000 characters, carrying the links, the CTA and what YouTube search reads. Omit it and the caption is used."
      },
      "disableDuet": {
        "type": "boolean",
        "description": "TIKTOK VIDEO ONLY — block Duets. TikTok’s photo-post API has no Duets, so this is refused on a photo/slideshow item rather than silently dropped."
      },
      "linkPicture": {
        "type": "string",
        "description": "FACEBOOK — override the IMAGE of the link preview: a public http(s) url Facebook fetches itself. Needs `link`. MEASURED 2026-09-17: Facebook only honours these when the Page’s business has VERIFIED the domain (Business Manager ▸ Brand safety ▸ Domains) — without that Meta refuses the post outright with “Only owners of the URL…”, so leave them out unless the brand owns and has verified that link’s domain."
      },
      "quotePostId": {
        "type": "string",
        "description": "THREADS ONLY — the id of the Threads post this one quotes."
      },
      "shareToFeed": {
        "type": "boolean",
        "description": "INSTAGRAM REEL — true puts the Reel in the Feed grid as well as the Reels tab. REELS ONLY. Left unset it follows Instagram’s own default; Hermoso does not flip it either way on the user’s behalf."
      },
      "thumbOffset": {
        "type": "number",
        "description": "INSTAGRAM REEL COVER, the other way — which frame becomes the cover, in MILLISECONDS from the start of the video. REELS ONLY. Use it instead of `coverUrl` when the right cover is already a frame of the clip."
      },
      "callToAction": {
        "enum": [
          "BOOK_TRAVEL",
          "BUY_NOW",
          "CALL_NOW",
          "DOWNLOAD",
          "GET_DIRECTIONS",
          "LEARN_MORE",
          "LIKE_PAGE",
          "MESSAGE_PAGE",
          "NO_BUTTON",
          "OPEN_LINK",
          "SHOP_NOW",
          "SIGN_UP",
          "WATCH_MORE"
        ],
        "type": "string",
        "description": "FACEBOOK — a real call-to-action BUTTON on the Page post. The types that open a destination (SHOP_NOW, LEARN_MORE, SIGN_UP, BUY_NOW, DOWNLOAD, OPEN_LINK, WATCH_MORE, BOOK_TRAVEL) need somewhere to go: the post’s own `link`, or `callToActionLink`. CALL_NOW, MESSAGE_PAGE, LIKE_PAGE and GET_DIRECTIONS act on the Page itself and take none."
      },
      "countryCodes": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "THREADS ONLY — two-letter country codes to limit who can see the post. Omit to show it everywhere."
      },
      "optimizeCopy": {
        "type": "boolean",
        "description": "RECOMMENDED when one caption goes to several channels: fit the shared caption to each channel’s own rules when you schedule it (the fitted caption is stored on the scheduled post, so what you scheduled is what publishes) wherever no per-channel caption was written. The angle and every claim stay the author’s; a channel with its own caption is left exactly as written. Off by default so nobody’s words are rewritten unasked."
      },
      "privacyLevel": {
        "enum": [
          "PUBLIC_TO_EVERYONE",
          "MUTUAL_FOLLOW_FRIENDS",
          "FOLLOWER_OF_CREATOR",
          "SELF_ONLY"
        ],
        "type": "string",
        "description": "TIKTOK — WHICH PRIVACY LEVEL the post goes out at, in TikTok’s own vocabulary. TikTok requires the USER to choose this from the levels their own account allows: call tiktok_creator_info, show them the real options, and pass back the one they picked — never a default and never a guess, which TikTok refuses at init. Omit it and the post falls back to the coarse `visibility` (private → SELF_ONLY, otherwise PUBLIC_TO_EVERYONE), which cannot express MUTUAL_FOLLOW_FRIENDS or FOLLOWER_OF_CREATOR at all. It must agree with the TikTok visibility (SELF_ONLY is the private one) and it is refused on a TikTok DRAFT, which carries no post info."
      },
      "replyControl": {
        "enum": [
          "everyone",
          "accounts_you_follow",
          "mentioned_only",
          "parent_post_author_only",
          "followers_only"
        ],
        "type": "string",
        "description": "THREADS ONLY — who may reply. Omit for Threads' own default (everyone)."
      },
      "thumbnailUrl": {
        "type": "string",
        "description": "YOUTUBE: the custom thumbnail, a Hermoso-hosted image (make_thumbnail, or upload_file for the user’s own). Omit it and a frame of the video is used; \"auto\" keeps YouTube’s pick."
      },
      "xQuotePostId": {
        "type": "string",
        "description": "X — the numeric id of an X post this one QUOTES: the last part of its URL. NAMED xQuotePostId, NOT quotePostId, because `quotePostId` on this same schedule belongs to THREADS. Billed at X’s higher LINK rate."
      },
      "collaborators": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "INSTAGRAM — a COLLAB post: up to 3 Instagram usernames invited to CO-AUTHOR it, so it appears on their profile too once they accept, with both handles in the header and the engagement shared. Handles only (\"hermosoai\"); a leading @ is fine. Instagram must be one of the `channels` — asking for collaborators on a schedule Instagram is not on is REFUSED now rather than discovered when it fires, and the other channels in a mixed schedule simply publish without co-authors. THE INVITE IS SENT WHEN THE POST FIRES, not when you schedule it, and it is PENDING until the other account accepts in their notifications; check with instagram_collaborators afterwards rather than telling the user it is live on both profiles."
      },
      "disableStitch": {
        "type": "boolean",
        "description": "TIKTOK VIDEO ONLY — block Stitches. Same photo-post rule as disableDuet."
      },
      "platformCover": {
        "type": "boolean",
        "description": "VIDEO COVER. Omit it (the default) and Hermoso sets the video’s best frame — the same frame as its Library thumbnail — as the cover on every channel that allows one (Instagram, Facebook, TikTok direct posts, LinkedIn Pages, Pinterest, Telegram, YouTube) — and on X, Threads and Bluesky, which have none, a blank first frame is replaced on a copy sent there only. true = send no cover and let the platform pick (usually the first frame). A cover you pass yourself always wins."
      },
      "replySettings": {
        "enum": [
          "following",
          "mentionedUsers",
          "subscribers",
          "verified"
        ],
        "type": "string",
        "description": "X — who may reply. Omit for everyone, which is the right default for a brand post."
      },
      "brandedContent": {
        "type": "boolean",
        "description": "TIKTOK — the PAID-PARTNERSHIP disclosure (TikTok’s brand_content_toggle): true when this post promotes a THIRD-PARTY business. It is a compliance declaration, not a preference — set it whenever the post is sponsored. TikTok only accepts branded content on a public or friends-only post, so it cannot ride a private/SELF_ONLY or draft TikTok item and the schedule is refused with the reason."
      },
      "disableComment": {
        "type": "boolean",
        "description": "TIKTOK — turn comments off on this post."
      },
      "linkAttachment": {
        "type": "string",
        "description": "THREADS ONLY — a full http(s) URL rendered as a link card. This is the ONLY way a Threads post carries a destination, and Threads attaches it to TEXT-ONLY posts (a post with media cannot also carry a card)."
      },
      "targetAudience": {
        "type": "object",
        "properties": {
          "degrees": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "industries": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "seniorities": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "geoLocations": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "jobFunctions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "fieldsOfStudy": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "organizations": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "staffCountRanges": {
            "type": "array",
            "items": {
              "enum": [
                "SIZE_1",
                "SIZE_2_TO_10",
                "SIZE_11_TO_50",
                "SIZE_51_TO_200",
                "SIZE_201_TO_500",
                "SIZE_501_TO_1000",
                "SIZE_1001_TO_5000",
                "SIZE_5001_TO_10000",
                "SIZE_10001_OR_MORE"
              ],
              "type": "string"
            }
          }
        },
        "description": "LINKEDIN COMPANY PAGE POST ONLY — show the post only to Page followers matching these facets (URNs or bare numeric ids; search_linkedin_ads_targeting finds them). LinkedIn requires the matching audience to be over 300 followers and refuses a smaller one. Personal-profile posts cannot be targeted."
      },
      "linkDescription": {
        "type": "string",
        "description": "FACEBOOK — override the DESCRIPTION of the link preview. Needs `link`. MEASURED 2026-09-17: Facebook only honours these when the Page’s business has VERIFIED the domain (Business Manager ▸ Brand safety ▸ Domains) — without that Meta refuses the post outright with “Only owners of the URL…”, so leave them out unless the brand owns and has verified that link’s domain."
      },
      "paidPartnership": {
        "type": "boolean",
        "description": "INSTAGRAM AND X — the PAID PARTNERSHIP label, a compliance declaration: set it when the post is sponsored, gifted or otherwise paid for. OPT-IN ONLY, never assume it on the user’s behalf. On Instagram, brandedContentSponsorIds names the brands behind it."
      },
      "callToActionLink": {
        "type": "string",
        "description": "FACEBOOK — where the button goes, when that is not the post’s own `link`."
      },
      "coverTimestampMs": {
        "type": "number",
        "description": "TIKTOK VIDEO ONLY — which frame TikTok uses as the cover, in milliseconds from the start. Omit and Hermoso uses the video’s best frame (platformCover:true leaves it to TikTok, which uses the first frame)."
      },
      "crossreshareToIg": {
        "type": "boolean",
        "description": "THREADS ONLY — when this fires, ALSO share it to the linked Instagram account as a STORY. Refused on a Threads carousel. No confirmation exists that the Story was created, so the result says it was requested."
      },
      "commercialContent": {
        "type": "boolean",
        "description": "TIKTOK — the COMMERCIAL CONTENT DISCLOSURE toggle: true when the post promotes a brand, product or service at all. TikTok requires at least one of yourBrand / brandedContent alongside it, and a post declaring itself commercial without naming which kind is refused. Setting either disclosure already implies this, so it is only needed to be explicit."
      },
      "instagramLocationId": {
        "type": "string",
        "description": "INSTAGRAM — tag a place (called locationId on post_to_meta; locationId here is the Google Business listing). It is the NUMERIC ID OF A FACEBOOK PAGE associated with that location, not a place name and not coordinates; a non-numeric value is refused rather than sent."
      },
      "visibilityByChannel": {
        "type": "object",
        "description": "override visibility for one channel, e.g. { \"tiktok\": \"draft\" } to go live everywhere but stage TikTok for review",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {
          "type": "string"
        }
      },
      "crossreshareDarkMode": {
        "type": "boolean",
        "description": "THREADS ONLY — render that Instagram Story in dark mode. Needs crossreshareToIg."
      },
      "linkedinOrganizationId": {
        "type": "string",
        "description": "LINKEDIN — publish as a COMPANY PAGE instead of the connected personal profile. The organization id from list_linkedin_pages. Omit and it posts as the person: an unset id means the profile, never “probably the company”. A Page can also carry VIDEO, which a personal profile cannot."
      },
      "brandedContentSponsorIds": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "INSTAGRAM — the numeric Instagram USER IDS of the brands behind that label (at most 2, and ids rather than @handles). Naming sponsors IS asking for the label, so setting these with `paidPartnership:false` is refused instead of publishing brand credits with no disclosure."
      }
    }
  }

  arguments 615 lines copy
• list_scheduled unknown never probed

  Show what is queued to post and what already went out. Each fired item reports PER-CHANNEL outcomes, so you can see that (say) Instagram published and TikTok failed on the same item rather than a single misleading verdict. Past items are rebuilt from published-post records, one row per channel; they are not job runs (use list_jobs for those). THE LIST IS COMPACT so it fits in one reply: the next 25 queued and the last 15 fired, captions shortened. Pass `id` for ONE post in full (every caption and setting, which you need before reschedule_post replaces a caption map), `channel` to filter, or `upcoming` / `fired` for more rows. Read-only, 0 credits.

  mcp-tool

  1234567891011121314151617181920212223242526

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "id": {
        "type": "string",
        "description": "one post id from this list: returns that post in full, every caption and setting included"
      },
      "brand": {
        "type": "string",
        "description": "WHICH BRAND to list — the id or exact name from list_brands. Needed when the post lives in a brand this connection is not pinned to: a post you can CREATE in a brand must be manageable there too, without switching the whole connection. A name that matches no brand, or two, is REFUSED."
      },
      "fired": {
        "type": "number",
        "description": "how many already-fired posts to list, most recent last (default 15, max 200)"
      },
      "channel": {
        "type": "string",
        "description": "only posts that include this channel, e.g. \"pinterest\" or \"x\""
      },
      "upcoming": {
        "type": "number",
        "description": "how many queued posts to list, soonest first (default 25, max 200)"
      }
    }
  }

  arguments 26 lines copy
• reschedule_post unknown never probed

  Change a post that is still QUEUED — move it to a different time, rewrite the caption, swap the media, add or drop a channel, or change which board / Page / company Page / listing it goes to. PASS ONLY WHAT CHANGES: an omitted field is left exactly as it was, and an explicit empty string CLEARS one (linkedinOrganizationId:"" moves a company-Page post back to the person’s own profile). The edited item is re-checked against the identical rules its create passed — visibility the channel can honour, per-channel length, media the channel can carry — so an edit can never slip past a refusal that a create would have caught. Get the id from list_scheduled. Something that already went out cannot be changed: a published post is edited or removed with manage_meta_post / manage_linkedin_post / delete_x_post, not rescheduled.

  mcp-tool

  123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "id"
    ],
    "properties": {
      "at": {
        "type": "string",
        "description": "the new time — ISO timestamp (2026-08-05T09:00:00Z) or epoch milliseconds. Must be in the future, at most 365 days out."
      },
      "id": {
        "type": "string",
        "description": "the scheduled post id from list_scheduled"
      },
      "link": {
        "type": "string"
      },
      "poll": {
        "type": "object",
        "required": [
          "options"
        ],
        "properties": {
          "options": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "durationMinutes": {
            "type": "number"
          }
        },
        "description": "X — replaces the poll; an empty options list removes it."
      },
      "tags": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "YOUTUBE — replaces the WHOLE tag list; an empty array [] clears the tags."
      },
      "brand": {
        "type": "string",
        "description": "WHICH BRAND this post is in — the id or exact name from list_brands. Needed when the post lives in a brand this connection is not pinned to: a post you can CREATE in a brand must be manageable there too, without switching the whole connection. A name that matches no brand, or two, is REFUSED."
      },
      "event": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string"
          },
          "endDate": {
            "type": "string"
          },
          "endTime": {
            "type": "string"
          },
          "startDate": {
            "type": "string"
          },
          "startTime": {
            "type": "string"
          }
        },
        "description": "GOOGLE BUSINESS — replaces the whole event record {title, startDate, startTime, endDate, endTime}."
      },
      "offer": {
        "type": "object",
        "properties": {
          "couponCode": {
            "type": "string"
          },
          "redeemOnlineUrl": {
            "type": "string"
          },
          "termsConditions": {
            "type": "string"
          }
        },
        "description": "GOOGLE BUSINESS — replaces the whole offer record {couponCode, redeemOnlineUrl, termsConditions}."
      },
      "place": {
        "type": "string",
        "description": "FACEBOOK — replaces the tagged place (the numeric id of its Facebook Page); an empty string removes it."
      },
      "story": {
        "type": "boolean",
        "description": "INSTAGRAM — true makes it a 24-hour Story, false an ordinary feed post. One image or one video, no carousel."
      },
      "title": {
        "type": "string",
        "description": "PINTEREST / YOUTUBE — replace the headline; \"\" clears it and goes back to deriving one from the caption"
      },
      "chatId": {
        "type": "string",
        "description": "TELEGRAM — send it to a different chat, group or channel (@username or numeric id). It can be changed but never cleared: telegram cannot publish without one."
      },
      "pageId": {
        "type": "string",
        "description": "FACEBOOK / INSTAGRAM / THREADS — publish from a different connected Page (list_meta_pages)"
      },
      "thread": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "X — replaces the WHOLE thread; an explicit [] drops back to a single post using the caption."
      },
      "altText": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        ],
        "description": "ACCESSIBILITY — replace the screen-reader description(s). A STRING describes every slide; an ARRAY describes them one at a time in slide order and REPLACES the whole list. \"\" clears it."
      },
      "boardId": {
        "type": "string",
        "description": "PINTEREST — move the Pin to a different board (list_pinterest_boards)"
      },
      "message": {
        "type": "string",
        "description": "replace the caption used for every channel that has no override"
      },
      "audience": {
        "type": "object",
        "properties": {
          "cities": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "minAge": {
            "type": "number"
          },
          "regions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "countries": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "description": "FACEBOOK — replaces who can see the Page post {countries, regions, cities, minAge}; {} removes the limit."
      },
      "captions": {
        "type": "object",
        "description": "replaces the WHOLE per-channel caption map — send every override you want to keep, not just the new one",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {
          "type": "string"
        }
      },
      "channels": {
        "type": "array",
        "items": {
          "enum": [
            "facebook",
            "instagram",
            "threads",
            "tiktok",
            "youtube",
            "linkedin",
            "x",
            "pinterest",
            "google_business",
            "bluesky",
            "telegram"
          ],
          "type": "string"
        },
        "description": "replaces the channel list"
      },
      "coverUrl": {
        "type": "string",
        "description": "INSTAGRAM REEL — replaces the cover image url; an empty string removes it."
      },
      "imageUrl": {
        "type": "string",
        "description": "swap the image; \"\" removes it"
      },
      "linkName": {
        "type": "string",
        "description": "FACEBOOK — replaces the link preview headline; an empty string removes the override."
      },
      "topicTag": {
        "type": "string",
        "description": "THREADS ONLY — one topic tag, without the leading #."
      },
      "videoUrl": {
        "type": "string",
        "description": "swap the video; \"\" removes it"
      },
      "xArticle": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string"
          },
          "headings": {
            "enum": [
              "blocks",
              "text"
            ],
            "type": "string"
          }
        },
        "description": "X: replaces the X Article (title, headings); {} makes it an ordinary X post again."
      },
      "audioName": {
        "type": "string",
        "description": "INSTAGRAM REEL — replaces the audio track name; an empty string removes it."
      },
      "imageUrls": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "replace the CAROUSEL slides, in order; an empty array [] drops the carousel and goes back to a single image. Omit to leave the slides exactly as they are. The edited item is re-checked against the same carousel rules the create passed, so adding a channel that cannot swipe is refused now rather than posting slide 1 later."
      },
      "slideText": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "link": {
              "type": "string"
            },
            "title": {
              "type": "string"
            },
            "description": {
              "type": "string"
            }
          }
        },
        "description": "PINTEREST CAROUSEL ONLY — per-slide title / description / link, aligned to slide order."
      },
      "topicType": {
        "enum": [
          "STANDARD",
          "EVENT",
          "OFFER",
          "ALERT"
        ],
        "type": "string",
        "description": "GOOGLE BUSINESS — the kind of Post; EVENT and OFFER both require `event`."
      },
      "trialReel": {
        "enum": [
          "MANUAL",
          "SS_PERFORMANCE",
          ""
        ],
        "type": "string",
        "description": "INSTAGRAM — replaces the trial-reel setting on a queued Reel (MANUAL or SS_PERFORMANCE); an explicit \"\" turns the trial off and it goes out as an ordinary Reel. Only takes effect while the post is still queued — a Reel already published cannot be converted into a trial."
      },
      "yourBrand": {
        "type": "boolean",
        "description": "TIKTOK — the own-brand disclosure; false turns it off."
      },
      "actionType": {
        "enum": [
          "BOOK",
          "ORDER",
          "SHOP",
          "LEARN_MORE",
          "SIGN_UP",
          "CALL"
        ],
        "type": "string",
        "description": "GOOGLE BUSINESS — the call-to-action button; \"\" clears it."
      },
      "locationId": {
        "type": "string",
        "description": "GOOGLE BUSINESS — a different listing (list_business_locations)"
      },
      "madeWithAi": {
        "type": "boolean",
        "description": "X — the AI-media label; false turns it off."
      },
      "visibility": {
        "enum": [
          "public",
          "unlisted",
          "private",
          "draft"
        ],
        "type": "string",
        "description": "NOTE: changing this without also naming visibilityByChannel clears any per-channel overrides, so \"make it all draft\" is not a no-op"
      },
      "aiGenerated": {
        "type": "boolean",
        "description": "INSTAGRAM / FACEBOOK REEL — Meta’s is_ai_generated self-disclosure. OMIT IT and Hermoso decides from provenance: a Hermoso render is declared, media that came through upload_file or from an external URL (the user’s own photographs or footage) is NOT — a real photo must never carry Instagram’s “AI info” label. Pass true or false only to override: false strips the label from something Hermoso would otherwise declare, true declares a render the user uploaded themselves."
      },
      "communityId": {
        "type": "string",
        "description": "X — the community to publish into; an empty string goes back to the main timeline."
      },
      "description": {
        "type": "string",
        "description": "YOUTUBE — replace the video description; \"\" clears it and the caption is used."
      },
      "disableDuet": {
        "type": "boolean",
        "description": "TIKTOK VIDEO ONLY — block Duets."
      },
      "linkPicture": {
        "type": "string",
        "description": "FACEBOOK — replaces the link preview image url; an empty string removes the override."
      },
      "quotePostId": {
        "type": "string",
        "description": "THREADS ONLY — the id of the Threads post this one quotes."
      },
      "shareToFeed": {
        "type": "boolean",
        "description": "INSTAGRAM REEL — whether the Reel also shows in the Feed grid."
      },
      "thumbOffset": {
        "type": "number",
        "description": "INSTAGRAM REEL — replaces the cover frame, in milliseconds; 0 removes it. Never together with coverUrl."
      },
      "callToAction": {
        "enum": [
          "BOOK_TRAVEL",
          "BUY_NOW",
          "CALL_NOW",
          "DOWNLOAD",
          "GET_DIRECTIONS",
          "LEARN_MORE",
          "LIKE_PAGE",
          "MESSAGE_PAGE",
          "NO_BUTTON",
          "OPEN_LINK",
          "SHOP_NOW",
          "SIGN_UP",
          "WATCH_MORE",
          ""
        ],
        "type": "string",
        "description": "FACEBOOK — replaces the button on the Page post; \"\" removes it."
      },
      "countryCodes": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "THREADS ONLY — two-letter country codes limiting who can see the post."
      },
      "optimizeCopy": {
        "type": "boolean",
        "description": "fit the shared caption to each channel’s own rules when you schedule it (the fitted caption is stored on the scheduled post, so what you scheduled is what publishes) wherever no per-channel caption was written; a channel with its own caption is left exactly as written. Send false to switch it off on this item."
      },
      "privacyLevel": {
        "enum": [
          "PUBLIC_TO_EVERYONE",
          "MUTUAL_FOLLOW_FRIENDS",
          "FOLLOWER_OF_CREATOR",
          "SELF_ONLY"
        ],
        "type": "string",
        "description": "TIKTOK — WHICH PRIVACY LEVEL the post goes out at, in TikTok’s own vocabulary. TikTok requires the USER to choose this from the levels their own account allows: call tiktok_creator_info, show them the real options, and pass back the one they picked — never a default and never a guess, which TikTok refuses at init. Omit it and the post falls back to the coarse `visibility` (private → SELF_ONLY, otherwise PUBLIC_TO_EVERYONE), which cannot express MUTUAL_FOLLOW_FRIENDS or FOLLOWER_OF_CREATOR at all. It must agree with the TikTok visibility (SELF_ONLY is the private one) and it is refused on a TikTok DRAFT, which carries no post info."
      },
      "replyControl": {
        "enum": [
          "everyone",
          "accounts_you_follow",
          "mentioned_only",
          "parent_post_author_only",
          "followers_only"
        ],
        "type": "string",
        "description": "THREADS ONLY — who may reply."
      },
      "thumbnailUrl": {
        "type": "string",
        "description": "YOUTUBE: replace the custom thumbnail; \"\" goes back to a frame of the video, \"auto\" to YouTube’s pick."
      },
      "xQuotePostId": {
        "type": "string",
        "description": "X — the post this one QUOTES; an empty string removes the quote. Named apart from the Threads `quotePostId` on this same schedule."
      },
      "collaborators": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "INSTAGRAM — replaces the WHOLE collab list (up to 3 usernames); an explicit [] removes the co-authors and the post goes out as an ordinary single-author post. Only takes effect if the post has not fired yet — an invite already sent cannot be withdrawn from here."
      },
      "disableStitch": {
        "type": "boolean",
        "description": "TIKTOK VIDEO ONLY — block Stitches."
      },
      "platformCover": {
        "type": "boolean",
        "description": "VIDEO COVER. Omit it (the default) and Hermoso sets the video’s best frame — the same frame as its Library thumbnail — as the cover on every channel that allows one — and on X, Threads and Bluesky, which have none, a blank first frame is replaced on a copy sent there only. true = send no cover and let the platform pick (usually the first frame). A cover you pass yourself always wins."
      },
      "replySettings": {
        "enum": [
          "following",
          "mentionedUsers",
          "subscribers",
          "verified"
        ],
        "type": "string",
        "description": "X — who may reply; \"\" goes back to everyone."
      },
      "brandedContent": {
        "type": "boolean",
        "description": "TIKTOK — the paid-partnership disclosure; false turns it off."
      },
      "disableComment": {
        "type": "boolean",
        "description": "TIKTOK — comments off on this post."
      },
      "linkAttachment": {
        "type": "string",
        "description": "THREADS ONLY — a full http(s) URL rendered as a link card on a TEXT-ONLY post. The only way a Threads post carries a destination."
      },
      "targetAudience": {
        "type": "object",
        "properties": {
          "degrees": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "industries": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "seniorities": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "geoLocations": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "jobFunctions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "fieldsOfStudy": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "organizations": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "staffCountRanges": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "description": "LINKEDIN COMPANY PAGE — replaces who sees the post; {} removes the limit. The matching audience must be over 300 followers."
      },
      "linkDescription": {
        "type": "string",
        "description": "FACEBOOK — replaces the link preview description; an empty string removes the override."
      },
      "paidPartnership": {
        "type": "boolean",
        "description": "INSTAGRAM AND X — the paid-partnership label; false turns it off."
      },
      "callToActionLink": {
        "type": "string",
        "description": "FACEBOOK — replaces where the button goes; an empty string falls back to the post link."
      },
      "coverTimestampMs": {
        "type": "number",
        "description": "TIKTOK VIDEO ONLY — cover frame in milliseconds."
      },
      "crossreshareToIg": {
        "type": "boolean",
        "description": "THREADS ONLY — also share to Instagram as a Story when it fires; false turns it off. Refused on a carousel."
      },
      "commercialContent": {
        "type": "boolean",
        "description": "TIKTOK — the COMMERCIAL CONTENT DISCLOSURE toggle: true when this post promotes a brand, product or service at all. TikTok requires at least one of yourBrand / brandedContent once it is on, and refuses a post that declares itself commercial without naming which kind. Either disclosure already implies it."
      },
      "instagramLocationId": {
        "type": "string",
        "description": "INSTAGRAM — replaces the tagged place (the numeric id of its Facebook Page); an empty string removes it. Not locationId, which is the Google Business listing."
      },
      "visibilityByChannel": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {
          "type": "string"
        }
      },
      "crossreshareDarkMode": {
        "type": "boolean",
        "description": "THREADS ONLY — dark-mode that Instagram Story. Needs crossreshareToIg."
      },
      "linkedinOrganizationId": {
        "type": "string",
        "description": "LINKEDIN — target a different company Page, or \"\" to post as the connected person instead"
      },
      "brandedContentSponsorIds": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "INSTAGRAM — replaces the sponsor user ids behind the paid-partnership label (at most 2); [] removes them."
      }
    }
  }

  arguments 544 lines copy
• cancel_scheduled unknown never probed

  Remove a queued post before it goes out. Get the id from list_scheduled. Only works while it is still queued — something already published cannot be unsent (use manage_meta_post to delete a Facebook/Instagram post after the fact).

  mcp-tool

  1234567891011121314151617

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "id"
    ],
    "properties": {
      "id": {
        "type": "string",
        "description": "the scheduled post id from list_scheduled"
      },
      "brand": {
        "type": "string",
        "description": "WHICH BRAND this post is in — the id or exact name from list_brands. Needed when the post lives in a brand this connection is not pinned to: a post you can CREATE in a brand must be manageable there too, without switching the whole connection. A name that matches no brand, or two, is REFUSED."
      }
    }
  }

  arguments 17 lines copy
• retry_scheduled unknown never probed

  Send a post that FAILED again. A scheduled post fans out across its channels INDEPENDENTLY, so a failure is usually PARTIAL — LinkedIn 401s while Instagram published fine — and this re-fires ONLY the channels that did not succeed by default (list_scheduled reports them as `retryable`). It re-queues the same content as a NEW post that goes out RIGHT AWAY — the queue picks it up on its next pass, within seconds — and the original keeps its failure record so the history still shows what went wrong. Naming a channel that already published is REFUSED rather than quietly posting a second time. Two independent belts stop a double-post: a channel that genuinely published can only REPLAY (nothing is posted), and a channel whose outcome is UNRESOLVED — the platform timed out and may be holding the post — refuses with that reason instead of guessing. Retry after fixing the cause — and you can fix it IN THIS CALL: pass `boardId`, `pageId`, `linkedinOrganizationId`, `locationId`, `message` or `captions` to correct the value that failed, and the corrected post is re-validated exactly like a fresh schedule. That matters because the commonest cause is a field, not an outage: a Pin aimed at the wrong board fails identically however many times it is re-sent. Anything you do not name is copied from the original. To send the same thing again ON PURPOSE, use duplicate_scheduled.

  mcp-tool

  12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "id"
    ],
    "properties": {
      "at": {
        "type": "string",
        "description": "hold the retry until a later time — ISO timestamp or epoch milliseconds. Leave it out to retry immediately, which is almost always what you want. A time you name here must be at least a minute from now, exactly like any other scheduled post."
      },
      "id": {
        "type": "string",
        "description": "the scheduled post id from list_scheduled"
      },
      "brand": {
        "type": "string",
        "description": "WHICH BRAND this post is in — the id or exact name from list_brands. Needed when the post lives in a brand this connection is not pinned to: a post you can CREATE in a brand must be manageable there too, without switching the whole connection. A name that matches no brand, or two, is REFUSED."
      },
      "chatId": {
        "type": "string",
        "description": "CORRECT THE TELEGRAM DESTINATION on retry — the @username or numeric id of the chat. A post aimed at a chat the bot is not in fails every time it is retried until this changes."
      },
      "pageId": {
        "type": "string",
        "description": "CORRECT THE PAGE on retry — which connected Facebook Page (and its linked Instagram/Threads) publishes, from list_meta_pages."
      },
      "boardId": {
        "type": "string",
        "description": "CORRECT THE BOARD on retry — the Pinterest board the Pin goes on, from list_pinterest_boards. A Pin aimed at a board Pinterest refuses fails the same way on every retry until this is changed."
      },
      "message": {
        "type": "string",
        "description": "CORRECT THE CAPTION on retry — use this when the original was refused for length or content. Anything not named here is copied from the original post."
      },
      "captions": {
        "type": "object",
        "description": "CORRECT ONE CHANNEL’S CAPTION on retry, e.g. { \"x\": \"...\" } when only that channel refused the text.",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {
          "type": "string"
        }
      },
      "channels": {
        "type": "array",
        "items": {
          "enum": [
            "facebook",
            "instagram",
            "threads",
            "tiktok",
            "youtube",
            "linkedin",
            "x",
            "pinterest",
            "google_business",
            "bluesky",
            "telegram"
          ],
          "type": "string"
        },
        "description": "retry only these channels (default: every channel that did not publish)"
      },
      "locationId": {
        "type": "string",
        "description": "CORRECT THE LISTING on retry — which Google Business Profile location, e.g. \"locations/123\" from list_business_locations."
      },
      "allowDuplicate": {
        "type": "boolean",
        "description": "ONLY for a channel you have checked by hand and confirmed the post is genuinely NOT there. It bypasses the double-post protection and can publish a second public copy, so never set it to work around a refusal you have not investigated."
      },
      "linkedinOrganizationId": {
        "type": "string",
        "description": "CORRECT THE LINKEDIN AUTHOR on retry — the company Page id from list_linkedin_pages. Set it to an empty string to fall back to the personal profile."
      }
    }
  }

  arguments 79 lines copy
• duplicate_scheduled unknown never probed

  Copy an existing scheduled or already-published post into a NEW queued post — the way to run a creative again, reuse a post that worked as the starting point for the next one, or re-send something after it went out. It copies the caption, media, per-channel captions, title, description, tags and the target board / Page / company Page / listing, and ANY of those can be overridden in the same call. Give a new time in `at`, or useQueue:true to drop it into the brand’s next free posting slot. The copy is INDEPENDENT — editing or cancelling it never touches the original — and it is a genuinely new post rather than a re-send, so it publishes even where the original already did. To re-fire only the channels that FAILED, use retry_scheduled instead.

  mcp-tool

  123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "id"
    ],
    "properties": {
      "at": {
        "type": "string",
        "description": "when the copy goes out — ISO timestamp or epoch milliseconds (default: an hour from now)"
      },
      "id": {
        "type": "string",
        "description": "the post to copy, from list_scheduled"
      },
      "link": {
        "type": "string"
      },
      "brand": {
        "type": "string",
        "description": "WHICH BRAND this post is in — the id or exact name from list_brands. Needed when the post lives in a brand this connection is not pinned to: a post you can CREATE in a brand must be manageable there too, without switching the whole connection. A name that matches no brand, or two, is REFUSED."
      },
      "title": {
        "type": "string"
      },
      "chatId": {
        "type": "string",
        "description": "TELEGRAM — which chat, group or channel the copy goes to (@username or numeric id)"
      },
      "pageId": {
        "type": "string",
        "description": "FACEBOOK / INSTAGRAM / THREADS — which connected Page (list_meta_pages)"
      },
      "boardId": {
        "type": "string",
        "description": "PINTEREST — the board for the copy (list_pinterest_boards)"
      },
      "message": {
        "type": "string",
        "description": "a different caption for the copy"
      },
      "captions": {
        "type": "object",
        "description": "per-channel caption overrides for the copy",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {
          "type": "string"
        }
      },
      "channels": {
        "type": "array",
        "items": {
          "enum": [
            "facebook",
            "instagram",
            "threads",
            "tiktok",
            "youtube",
            "linkedin",
            "x",
            "pinterest",
            "google_business",
            "bluesky",
            "telegram"
          ],
          "type": "string"
        },
        "description": "post the copy to these channels instead of the original’s"
      },
      "imageUrl": {
        "type": "string"
      },
      "timezone": {
        "type": "string",
        "description": "IANA zone for the queue, e.g. \"America/New_York\""
      },
      "useQueue": {
        "type": "boolean",
        "description": "instead of naming a time, take the brand’s next free posting slot"
      },
      "videoUrl": {
        "type": "string"
      },
      "imageUrls": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "CAROUSEL — an ORDERED list of image URLs published as ONE swipeable post"
      },
      "locationId": {
        "type": "string",
        "description": "GOOGLE BUSINESS — which listing (list_business_locations)"
      },
      "visibility": {
        "enum": [
          "public",
          "unlisted",
          "private",
          "draft"
        ],
        "type": "string"
      },
      "linkedinOrganizationId": {
        "type": "string",
        "description": "LINKEDIN — publish the copy as this company Page (list_linkedin_pages)"
      }
    }
  }

  arguments 111 lines copy
• get_post_refill unknown never probed

  Show the automatic posting refill for this brand: whether it is on, whether it is in dry-run (preview) mode, how many days ahead it fills, its render budget, when it next runs, and how many posts are queued right now. It also names the channels that CANNOT be posted to and why. Read-only, free.

  mcp-tool

  12345

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {}
  }

  arguments 5 lines copy
• set_post_refill unknown never probed

  Turn the automatic posting refill on or off and set how it behaves. PASS ONLY WHAT CHANGES. `enabled:false` is the PAUSE — it removes the recurring job outright, and posts already queued are left alone (cancel those with cancel_scheduled if you want them gone). It starts in dryRun, which plans and previews without queueing; set dryRun:false only once a human has read a preview from run_post_refill. THE CADENCE IS THE BRAND’S POSTING TIMES, not a number here: three posting times means three posts a day. Raising maxImagesPerDay / maxVideosPerDay / maxCreditsPerDay above 0 lets it SPEND on new creative — at 0 (the default) it only reuses renders already in the Library and costs nothing.

  mcp-tool

  1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "chatId": {
        "type": "string",
        "description": "TELEGRAM — which chat, group or channel posts go to (@username or numeric id). Without one, telegram is skipped: there is no default chat and posting to the wrong one is a public mistake."
      },
      "dryRun": {
        "type": "boolean",
        "description": "true (the default) = plan and preview only, queue nothing. Set false ONLY after a human has read a preview."
      },
      "pageId": {
        "type": "string",
        "description": "FACEBOOK / INSTAGRAM / THREADS — which connected Page to publish from (list_meta_pages). Omit for the brand’s only Page."
      },
      "boardId": {
        "type": "string",
        "description": "PINTEREST — which board Pins go on (list_pinterest_boards). Without one, Pinterest is skipped: a Pin on the wrong board is a public mistake, so it is never guessed."
      },
      "enabled": {
        "type": "boolean",
        "description": "on/off. false PAUSES it: the recurring job is deleted and nothing new is queued. Already-queued posts are untouched."
      },
      "channels": {
        "type": "array",
        "items": {
          "enum": [
            "facebook",
            "instagram",
            "threads",
            "tiktok",
            "youtube",
            "linkedin",
            "x",
            "pinterest",
            "google_business",
            "bluesky",
            "telegram"
          ],
          "type": "string"
        },
        "description": "restrict it to these channels. Omit (or send an empty list) to use every connected channel that can carry each post."
      },
      "daysAhead": {
        "type": "number",
        "description": "how far ahead to keep the queue full, 1–30 (default 7)"
      },
      "postsPerDay": {
        "type": "number",
        "description": "cap the posts per day BELOW the number of posting times. 0 (default) = use every posting time, which is where \"3 a day\" comes from. To post MORE per day, add posting times instead."
      },
      "maxImagesPerDay": {
        "type": "number",
        "description": "how many NEW images a day it may render when the Library runs dry. 0 (default) = none, spend nothing."
      },
      "maxVideosPerDay": {
        "type": "number",
        "description": "how many NEW videos a day it may render. 0 (default) = none. Video is the expensive one — hundreds of credits each."
      },
      "maxCreditsPerDay": {
        "type": "number",
        "description": "a hard credit ceiling per day, checked BEFORE any render starts. It binds independently of the counts above."
      },
      "assetCooldownDays": {
        "type": "number",
        "description": "how long before a Library render may be posted again (default 30). It never repeats one inside this window — it queues fewer posts and says so."
      },
      "linkedinOrganizationId": {
        "type": "string",
        "description": "LINKEDIN — which company Page to post as (list_linkedin_pages). A single shared Page is used automatically; a Page that is not shared with this brand is ignored rather than failing the whole post."
      }
    }
  }

  arguments 74 lines copy
• run_post_refill unknown never probed

  Run the refill NOW instead of waiting for its daily turn. DRY BY DEFAULT: it returns the exact posts it WOULD queue — the caption, the creative, the channels and the per-channel visibility — without queueing anything or spending anything on creative. Pass dryRun:false to actually queue them. SHOW THE PREVIEW TO THE USER BEFORE EVER PASSING dryRun:false; these go onto real public accounts. Every caption is screened against the brand’s own voice rules and a failing one is dropped, so a plan can legitimately come back shorter than the cadence — the reason is in the notes.

  mcp-tool

  1234567891011121314

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "force": {
        "type": "boolean",
        "description": "plan even while the refill is switched off — useful for showing someone what it would do before they turn it on. Combined with dryRun:false it still respects a stored dryRun."
      },
      "dryRun": {
        "type": "boolean",
        "description": "default TRUE (preview only). false actually queues the posts."
      }
    }
  }

  arguments 14 lines copy
• post_to_linkedin unknown never probed

  Publish a post to the user’s connected LinkedIn profile — text, and optionally an image (pass its served URL as imageUrl). The image does NOT have to be something Hermoso generated: LinkedIn is served the bytes from us, so the URL must be Hermoso-hosted, and upload_file turns ANY file the user already has into exactly that. This PUBLISHES immediately and PUBLICLY — ALWAYS show the user the exact text and get an explicit yes BEFORE calling. Needs a connected LinkedIn account (Settings ▸ Connectors ▸ LinkedIn).

  mcp-tool

  12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "text"
    ],
    "properties": {
      "hook": {
        "type": "string",
        "description": "WHAT ANGLE THIS POST IS BUILT ON — the single most valuable field here, and the only moment it can ever be recorded. post_performance groups on it to answer \"which hooks work\", and it needs 5 posts sharing ONE hook before it will call anything a winner, so REUSE THE SAME WORDING across a campaign instead of rephrasing it every time. Best of all, pass a hook id from list_hooks (e.g. \"direct_callout\", \"mid_problem\", \"before_after\") — those fold onto a stable key however they are spelled, so a whole brand accumulates evidence on one row. Your own wording is fine too; it just only groups when you repeat it exactly. Omitting it means this post can never vote on which hook works."
      },
      "text": {
        "type": "string",
        "description": "the post text"
      },
      "brand": {
        "type": "string",
        "description": "WHICH BRAND this post belongs to — the id or exact name from list_brands (a workspace shared with you: its profile id). Use it whenever the account has more than one brand and you are not certain which one this connection is pinned to: it beats the pin for THIS CALL ONLY and changes nothing about the connection. A name that matches no brand, or two brands, is REFUSED and nothing is posted — never resolved to the pin, which is the account you were guarding against."
      },
      "subject": {
        "type": "string",
        "description": "WHAT THIS POST IS ABOUT — the product, feature, offer or theme (e.g. \"winter coat\", \"free trial\", \"founder story\"). The second grouping axis in post_performance. Same rule as hook: reuse the exact wording so posts about one subject land in one group."
      },
      "imageUrl": {
        "type": "string",
        "description": "a Hermoso-hosted image URL to attach (≤12MB) — a Hermoso render, or ANY file of the user’s own put through upload_file first. An arbitrary external host is refused (we fetch the bytes ourselves)."
      },
      "imageUrls": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "A CAROUSEL IS NOT AVAILABLE ON A PERSONAL PROFILE — LinkedIn's organic multi-image post publishes from a COMPANY PAGE. Passing several here is refused by name rather than posting slide 1; use post_to_linkedin_page instead."
      },
      "visibility": {
        "enum": [
          "PUBLIC",
          "CONNECTIONS"
        ],
        "type": "string",
        "description": "default PUBLIC"
      },
      "allowDuplicate": {
        "type": "boolean",
        "description": "post it even though an identical post was just made or attempted. Only pass this when the user genuinely wants the same thing posted twice, or when you have LOOKED at the account and confirmed a timed-out attempt did not land."
      },
      "idempotencyKey": {
        "type": "string",
        "description": "SAFE RETRIES. Publishing can take minutes (a video upload, a carousel of ten slides) and a transport can time out while the post SUCCEEDS — retrying blind is how the same thing gets posted twice. Pass any stable string here and a repeat of the SAME publish returns the ORIGINAL post id instead of posting again (24h). You do not have to: an identical publish is auto-recognised for 10 minutes anyway. If a call times out or errors ambiguously, CALL AGAIN WITH THE SAME KEY — that is the safe move, and it will either report the original post or publish it for the first time. It never posts twice."
      }
    }
  }

  arguments 52 lines copy
• post_to_x unknown never probed

  Publish to the user’s connected X (Twitter) account — a single post, a post with an image or video render attached, a reply to an existing post, or a whole THREAD (pass `thread` as an array and each part is posted as a reply to the one before). This PUBLISHES immediately and PUBLICLY — ALWAYS show the user the exact text and get an explicit yes BEFORE calling. Can also run a POLL (2-4 options) instead of media, and restrict who may reply. LENGTH IS THE POSTING ACCOUNT’S, NOT A FLAT 280: 280 characters on an ordinary account, but UP TO 25,000 if that account has X Premium. Hermoso reads the account’s own subscription from X and sends the post rather than refusing something it may be entitled to; if X declines it on length, the reply says so and names the subscription X reported. Over 25,000 is refused for free — that is X’s own ceiling on every account. Text is NEVER truncated. AND A LONG POST IS CHEAPER THAN A THREAD: it is ONE billed X call where the same words split across five posts are five, so prefer one long post over threading when the account has Premium. Only the first ~280 characters show in the timeline; the rest sits behind “Show more”. Write altText whenever you attach a render. COSTS CREDITS: X charges per API request, so every post in a thread is billed, and a post containing a LINK costs roughly 13× one without — mention the cost before publishing a long thread. Each brand also has a rolling 24-hour ceiling on what it can spend at X, and a request that would cross it is refused WHOLE before anything publishes, so a batch of posts is bounded rather than open-ended. THIS TOOL POSTS ORGANICALLY — it does not create an ad campaign. X ads are built with create_x_ads_campaign → create_x_ads_line_item → create_x_ads_promoted_tweet, and a promoted post needs a post id, so publish here first and promote that post. Needs X connected (Settings ▸ Connectors ▸ X).

  mcp-tool

  123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "hook": {
        "type": "string",
        "description": "WHAT ANGLE THIS POST IS BUILT ON — the single most valuable field here, and the only moment it can ever be recorded. post_performance groups on it to answer \"which hooks work\", and it needs 5 posts sharing ONE hook before it will call anything a winner, so REUSE THE SAME WORDING across a campaign instead of rephrasing it every time. Best of all, pass a hook id from list_hooks (e.g. \"direct_callout\", \"mid_problem\", \"before_after\") — those fold onto a stable key however they are spelled, so a whole brand accumulates evidence on one row. Your own wording is fine too; it just only groups when you repeat it exactly. Omitting it means this post can never vote on which hook works."
      },
      "poll": {
        "type": "object",
        "required": [
          "options"
        ],
        "properties": {
          "options": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "2-4 choices, max 25 characters each"
          },
          "durationMinutes": {
            "type": "number",
            "description": "5 to 10080 minutes (7 days); default 1440 = one day"
          }
        },
        "description": "run a poll on the post. X does not allow a poll and media on the same post, and a poll cannot ride on a thread."
      },
      "text": {
        "type": "string",
        "description": "the post text. 280 characters without X Premium, up to 25,000 with it — write the full thing, it is never truncated. Use this OR thread, not both."
      },
      "brand": {
        "type": "string",
        "description": "WHICH BRAND this post belongs to — the id or exact name from list_brands (a workspace shared with you: its profile id). Use it whenever the account has more than one brand and you are not certain which one this connection is pinned to: it beats the pin for THIS CALL ONLY and changes nothing about the connection. A name that matches no brand, or two brands, is REFUSED and nothing is posted — never resolved to the pin, which is the account you were guarding against."
      },
      "thread": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "a thread: each string is one post, published in order, each replying to the previous. Max 25. Each part follows the same length rule as `text`, and on an X Premium account ONE long post is usually both better reading and cheaper than a thread."
      },
      "account": {
        "type": "string",
        "description": "WHICH connected account of this channel to post as — its @handle or id from list_connector_accounts. Needed only when the brand has more than one x account connected (several and none named is refused by name, never guessed); omit when there is one."
      },
      "altText": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        ],
        "description": "accessibility description of the attached media, max 1000 characters — write one whenever you attach a render. Costs a small extra amount: X bills one metadata write PER media. With SEVERAL media, pass an ARRAY aligned to their order — X attaches alt text per media id, and a single string describes only the FIRST one (X renders up to four media as a GRID, not a carousel, so one sentence would be wrong for the other three)."
      },
      "subject": {
        "type": "string",
        "description": "WHAT THIS POST IS ABOUT — the product, feature, offer or theme (e.g. \"winter coat\", \"free trial\", \"founder story\"). The second grouping axis in post_performance. Same rule as hook: reuse the exact wording so posts about one subject land in one group."
      },
      "imageUrl": {
        "type": "string",
        "description": "alias of mediaUrl for an IMAGE — same as passing it as mediaUrl"
      },
      "mediaUrl": {
        "type": "string",
        "description": "a Hermoso render (image or video) to attach to the first post — pass its served URL, or an upload_file url for external media"
      },
      "videoUrl": {
        "type": "string",
        "description": "alias of mediaUrl for a VIDEO — same as passing it as mediaUrl"
      },
      "mediaUrls": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "UP TO FOUR Hermoso-hosted media attached to ONE post — X’s own schema caps media_ids at 4. X renders them as a GRID: every image visible at once, nothing to swipe to. That is NOT a carousel, and a numbered \"1/6 · SWIPE\" slide deck must still not be sent here — it would publish as a grid and the \"swipe\" instruction would make no sense. Order decides the layout. On a thread the media rides the FIRST post; give each later part its own post to attach more. Mutually exclusive with mediaUrl, and more than 4 is refused before anything is uploaded."
      },
      "replyToId": {
        "type": "string",
        "description": "numeric id of an existing X post to reply to. X ONLY ACCEPTS AN API REPLY TO A POST THAT MENTIONS THIS ACCOUNT OR THAT THIS ACCOUNT WROTE (X policy since Feb 2026, every tier below Enterprise): a cold reply under a stranger's post is refused by X with \"You can only reply to or quote posts where you are mentioned or are the author\" and nothing is posted. Reply to those from x.com itself; use this for replies in your own threads and to people who tagged you."
      },
      "communityId": {
        "type": "string",
        "description": "publish into an X COMMUNITY instead of the main timeline — the number in the community’s own URL (x.com/i/communities/<id>). The connected account must be a MEMBER of it; X answers a non-member and a non-existent id with the same refusal and does not separate them."
      },
      "quotePostId": {
        "type": "string",
        "description": "numeric id of a post to QUOTE — X renders the quoted post inside yours. This is NOT replyToId: a reply sits under the original in its thread, a quote stands alone on your own timeline with the original embedded, which is the one you want for commentary. X makes a quote mutually exclusive with media and with a poll (their own schema), and a quote is billed at the higher LINK rate because X appends the quoted post’s t.co URL whatever your text says. Same X rule as replyToId: a quote of a post that does not mention this account is refused by X."
      },
      "platformCover": {
        "type": "boolean",
        "description": "VIDEO COVER. X has no cover setting and shows the video’s FIRST frame, so by default Hermoso checks it and, only when that frame is blank (a template ad’s empty opening card), sends X a copy with the first frame replaced by the video’s best frame. Your Library file is never changed. true = send the file exactly as it is."
      },
      "replySettings": {
        "enum": [
          "following",
          "mentionedUsers",
          "subscribers",
          "verified"
        ],
        "type": "string",
        "description": "restrict who can reply — omit for everyone, which is the right default for a brand post"
      },
      "paidPartnership": {
        "type": "boolean",
        "description": "label the post a PAID PARTNERSHIP on X — the same disclosure Hermoso already ships for TikTok. OPT-IN ONLY: set it when the post is sponsored, gifted or otherwise paid for, and never assume it on the user’s behalf."
      }
    }
  }

  arguments 116 lines copy
• post_x_article unknown never probed

  Publish a long-form ARTICLE to the user’s connected X (Twitter) account — X’s own long-form format, which is a different thing from a long POST. Give it a `title` and a `body` written in MARKDOWN (or plain prose) and Hermoso converts it into the DraftJS `content_state` structure X requires: headings, paragraphs, bulleted and numbered lists, blockquotes, bold / italic / strikethrough, links, horizontal rules, fenced code blocks and pipe tables all carry across. FORMATTING IS NEVER SILENTLY DROPPED — anything X Articles cannot represent (inline `code`, an inline image) REFUSES the article for free and names exactly what and why, and `allowLossy: true` is the explicit way to publish it as plain text anyway. THE HARD LIMIT TO PLAN AROUND: X allows only about 10 Article DRAFTS and 5 Article PUBLISHES per account per DAY, it publishes that cap nowhere, and it counts a FAILED attempt against them — so never iterate on an article by republishing it, and use `publish: false` to save a draft for the user to read in X’s own composer when they want to review before it goes out. This PUBLISHES immediately and PUBLICLY: show the user the full text and get an explicit yes first, because a published Article can NEVER be edited (X’s own rule — edit_x_post will refuse it) and the only remedy is to delete and republish, which costs another of the five. An Article appears in the timeline as a title card, not as body text; readers open it. Costs credits (X bills per API request, and this is three of them). Needs X connected (Settings ▸ Connectors ▸ X).

  mcp-tool

  1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "title",
      "body"
    ],
    "properties": {
      "body": {
        "type": "string",
        "description": "the article body, as markdown or plain prose. Markdown headings, lists, quotes, links, emphasis, ``` code fences and | pipe | tables | are all converted to X’s own Article structure."
      },
      "hook": {
        "type": "string",
        "description": "WHAT ANGLE THIS POST IS BUILT ON — the single most valuable field here, and the only moment it can ever be recorded. post_performance groups on it to answer \"which hooks work\", and it needs 5 posts sharing ONE hook before it will call anything a winner, so REUSE THE SAME WORDING across a campaign instead of rephrasing it every time. Best of all, pass a hook id from list_hooks (e.g. \"direct_callout\", \"mid_problem\", \"before_after\") — those fold onto a stable key however they are spelled, so a whole brand accumulates evidence on one row. Your own wording is fine too; it just only groups when you repeat it exactly. Omitting it means this post can never vote on which hook works."
      },
      "brand": {
        "type": "string",
        "description": "WHICH BRAND this post belongs to — the id or exact name from list_brands (a workspace shared with you: its profile id). Use it whenever the account has more than one brand and you are not certain which one this connection is pinned to: it beats the pin for THIS CALL ONLY and changes nothing about the connection. A name that matches no brand, or two brands, is REFUSED and nothing is posted — never resolved to the pin, which is the account you were guarding against."
      },
      "title": {
        "type": "string",
        "description": "the Article title — X requires one and refuses a draft without it. This is what shows on the timeline card."
      },
      "publish": {
        "type": "boolean",
        "description": "default true. Pass false to save it as a DRAFT in the account’s X Articles composer instead — nothing becomes public, the user can review and publish it from X, and it does not spend one of the five daily publishes."
      },
      "subject": {
        "type": "string",
        "description": "WHAT THIS POST IS ABOUT — the product, feature, offer or theme (e.g. \"winter coat\", \"free trial\", \"founder story\"). The second grouping axis in post_performance. Same rule as hook: reuse the exact wording so posts about one subject land in one group."
      },
      "headings": {
        "enum": [
          "blocks",
          "text"
        ],
        "type": "string",
        "description": "how headings are rendered. “blocks” (default) uses X’s own heading block types for # and ## headings; ### and deeper become bold lines, because X Articles refuse a third-level heading (the reply says so). “text” renders every heading as a BOLD standalone paragraph instead: the words survive and the heading structure does not, and the reply says so."
      },
      "allowLossy": {
        "type": "boolean",
        "description": "publish even though part of the source cannot be represented on X, rendering those parts as plain text. OFF by default and it should usually stay off — silently publishing a user’s copy with formatting missing is worse than refusing and telling them."
      },
      "coverImageUrl": {
        "type": "string",
        "description": "optional cover picture for the Article — a Hermoso render URL or an upload_file url. Must be a STILL image; X Article covers are not videos."
      }
    }
  }

  arguments 50 lines copy
• list_pinterest_boards unknown never probed

  List the boards on the user’s connected Pinterest account — id, name, privacy and pin count. ALWAYS call this before post_to_pinterest and let the USER pick: Pinterest requires a board and Hermoso never chooses one for them. Read-only, 0 credits. Needs Pinterest connected (Settings ▸ Connectors ▸ Pinterest).

  mcp-tool

  12345678910111213141516

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "privacy": {
        "enum": [
          "ALL",
          "PUBLIC",
          "PROTECTED",
          "SECRET"
        ],
        "type": "string",
        "description": "filter by board privacy; default is everything the connection can see"
      }
    }
  }

  arguments 16 lines copy
• post_to_pinterest unknown never probed

  Create a Pin on one of the user’s Pinterest boards from any finished visual they have — image, video, or a 2–5 slide CAROUSEL (pass the slides in order as imageUrls[] and Pinterest publishes one swipeable Pin). Title, description and destination link ride along. The link is what makes a Pin drive traffic, so ask for it rather than omitting it, and the description is the text Pinterest search actually reads. boardId is REQUIRED: call list_pinterest_boards first and let the user choose. This PUBLISHES to their public profile — confirm the board, title and link before calling. Video Pins take a minute or two while Pinterest ingests the file. Needs Pinterest connected (Settings ▸ Connectors ▸ Pinterest).

  mcp-tool

  123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "boardId"
    ],
    "properties": {
      "hook": {
        "type": "string",
        "description": "WHAT ANGLE THIS POST IS BUILT ON — the single most valuable field here, and the only moment it can ever be recorded. post_performance groups on it to answer \"which hooks work\", and it needs 5 posts sharing ONE hook before it will call anything a winner, so REUSE THE SAME WORDING across a campaign instead of rephrasing it every time. Best of all, pass a hook id from list_hooks (e.g. \"direct_callout\", \"mid_problem\", \"before_after\") — those fold onto a stable key however they are spelled, so a whole brand accumulates evidence on one row. Your own wording is fine too; it just only groups when you repeat it exactly. Omitting it means this post can never vote on which hook works."
      },
      "link": {
        "type": "string",
        "description": "destination URL the Pin clicks through to"
      },
      "brand": {
        "type": "string",
        "description": "WHICH BRAND this post belongs to — the id or exact name from list_brands (a workspace shared with you: its profile id). Use it whenever the account has more than one brand and you are not certain which one this connection is pinned to: it beats the pin for THIS CALL ONLY and changes nothing about the connection. A name that matches no brand, or two brands, is REFUSED and nothing is posted — never resolved to the pin, which is the account you were guarding against."
      },
      "title": {
        "type": "string",
        "description": "Pin title, max 100 characters"
      },
      "account": {
        "type": "string",
        "description": "WHICH connected account of this channel to post as — its @handle or id from list_connector_accounts. Needed only when the brand has more than one pinterest account connected (several and none named is refused by name, never guessed); omit when there is one."
      },
      "altText": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        ],
        "description": "accessibility alt text, max 500 characters. PIN-LEVEL: Pinterest’s API has no per-item alt text at all, so on a CAROUSEL the FIRST description is used for the whole Pin and the reply states that the others were not sent."
      },
      "boardId": {
        "type": "string",
        "description": "numeric board id from list_pinterest_boards — the user picks it, never guess"
      },
      "subject": {
        "type": "string",
        "description": "WHAT THIS POST IS ABOUT — the product, feature, offer or theme (e.g. \"winter coat\", \"free trial\", \"founder story\"). The second grouping axis in post_performance. Same rule as hook: reuse the exact wording so posts about one subject land in one group."
      },
      "imageUrl": {
        "type": "string",
        "description": "a Hermoso render image URL (or an upload_file url)"
      },
      "videoUrl": {
        "type": "string",
        "description": "a Hermoso render video URL — takes 1–2 minutes to ingest"
      },
      "imageUrls": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "CAROUSEL — an ORDERED list of image (and, where the channel allows, video) URLs published as ONE post the viewer swipes through. THIS IS NOT “post several” — it is a single post with several slides, which is what a multi-slide creative (a listicle, a “1/6 · SWIPE” deck) actually needs; publishing only its first slide tells the viewer to swipe at something that cannot. The ORDER is the product. Limits per channel: Instagram 2–10 (images, videos or a mix), Threads 2–20 (mix allowed), Facebook 2+ (Meta publishes no documented maximum; Hermoso caps the upload fan-out at 30 and says so), LinkedIn company Pages 2–20 (images only), Pinterest 2–5 (images only), TikTok up to 35. One url here is simply an ordinary single post. Anything a channel cannot do is REFUSED with the real reason — nothing is ever quietly downgraded to one slide."
      },
      "slideText": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "link": {
              "type": "string"
            },
            "title": {
              "type": "string"
            },
            "description": {
              "type": "string"
            }
          }
        },
        "description": "PINTEREST CAROUSEL ONLY — per-slide title, description and destination LINK, one object per slide in slide order. This is the ONLY genuine per-slide caption on any channel Hermoso publishes to: slide 4 can send people to the product ON slide 4, where every other platform gives a carousel one shared caption. Omit any field to leave it unset; the Pin’s own title/description/link still describe the Pin as a whole. Pinterest publishes no length limit on these, so nothing is truncated. More entries than slides is refused rather than dropped."
      },
      "description": {
        "type": "string",
        "description": "Pin description, max 800 characters — this is what Pinterest search reads"
      },
      "coverImageUrl": {
        "type": "string",
        "description": "video Pins only — a render to use as the cover frame"
      },
      "platformCover": {
        "type": "boolean",
        "description": "VIDEO COVER. Omit it (the default) and Hermoso sets the video’s best frame — the same frame as its Library thumbnail — as the cover (on Pinterest the frame rides as the cover image). true = send no cover and let the platform pick (usually the first frame). A cover you pass yourself always wins."
      },
      "allowDuplicate": {
        "type": "boolean",
        "description": "post it even though an identical post was just made or attempted. Only pass this when the user genuinely wants the same thing posted twice, or when you have LOOKED at the account and confirmed a timed-out attempt did not land."
      },
      "boardSectionId": {
        "type": "string",
        "description": "optional section within the board"
      },
      "idempotencyKey": {
        "type": "string",
        "description": "SAFE RETRIES. Publishing can take minutes (a video upload, a carousel of ten slides) and a transport can time out while the post SUCCEEDS — retrying blind is how the same thing gets posted twice. Pass any stable string here and a repeat of the SAME publish returns the ORIGINAL post id instead of posting again (24h). You do not have to: an identical publish is auto-recognised for 10 minutes anyway. If a call times out or errors ambiguously, CALL AGAIN WITH THE SAME KEY — that is the safe move, and it will either report the original post or publish it for the first time. It never posts twice."
      }
    }
  }

  arguments 108 lines copy
• list_business_locations unknown never probed

  List the Google Business Profile listings SHARED WITH THIS BRAND — id, title, address, website and Maps link. These are the only listings anything here can post to or read: one Google login often manages several businesses (an agency manages its clients’), and the user ticks which of them belong to this brand. Call this before posting whenever more than one is shared and let the USER pick: a Post on the wrong storefront is a public mistake Hermoso will not make for them. If nothing is shared, ask the user to choose — list_connector_accounts("google_business") then set_connector_accounts — and never name or guess a listing. Read-only, 0 credits. Needs Google Business Profile connected (Settings ▸ Connectors ▸ Google Business Profile).

  mcp-tool

  12345

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {}
  }

  arguments 5 lines copy
• post_to_google_business unknown never probed

  Publish a Post to the brand’s Google Business Profile — the panel that appears on Google Search and Maps for the business. Text, optionally ONE PHOTO, and a call-to-action button. Google’s Posts API accepts NO VIDEO, so pass a still image. This PUBLISHES immediately and publicly on the business listing — show the user the exact text, photo and button and get an explicit yes BEFORE calling. If the account manages several listings, call list_business_locations first and pass locationId. EVENT and OFFER posts both REQUIRE a title and a start date (Google’s rule). On an OFFER, Google IGNORES the button’s link — pass redeemOnlineUrl instead. A CALL button dials the number on the listing and takes no link. Needs Google Business Profile connected (Settings ▸ Connectors ▸ Google Business Profile).

  mcp-tool

  123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "hook": {
        "type": "string",
        "description": "WHAT ANGLE THIS POST IS BUILT ON — the single most valuable field here, and the only moment it can ever be recorded. post_performance groups on it to answer \"which hooks work\", and it needs 5 posts sharing ONE hook before it will call anything a winner, so REUSE THE SAME WORDING across a campaign instead of rephrasing it every time. Best of all, pass a hook id from list_hooks (e.g. \"direct_callout\", \"mid_problem\", \"before_after\") — those fold onto a stable key however they are spelled, so a whole brand accumulates evidence on one row. Your own wording is fine too; it just only groups when you repeat it exactly. Omitting it means this post can never vote on which hook works."
      },
      "link": {
        "type": "string",
        "description": "the URL the button opens — not for CALL, and ignored on an OFFER"
      },
      "brand": {
        "type": "string",
        "description": "WHICH BRAND this post belongs to — the id or exact name from list_brands (a workspace shared with you: its profile id). Use it whenever the account has more than one brand and you are not certain which one this connection is pinned to: it beats the pin for THIS CALL ONLY and changes nothing about the connection. A name that matches no brand, or two brands, is REFUSED and nothing is posted — never resolved to the pin, which is the account you were guarding against."
      },
      "title": {
        "type": "string",
        "description": "headline — REQUIRED for EVENT and OFFER"
      },
      "endDate": {
        "type": "string",
        "description": "YYYY-MM-DD, defaults to startDate"
      },
      "subject": {
        "type": "string",
        "description": "WHAT THIS POST IS ABOUT — the product, feature, offer or theme (e.g. \"winter coat\", \"free trial\", \"founder story\"). The second grouping axis in post_performance. Same rule as hook: reuse the exact wording so posts about one subject land in one group."
      },
      "summary": {
        "type": "string",
        "description": "the body text of the Post"
      },
      "imageUrl": {
        "type": "string",
        "description": "a Hermoso render image URL (or an upload_file url) to show on the Post"
      },
      "startDate": {
        "type": "string",
        "description": "YYYY-MM-DD — REQUIRED for EVENT and OFFER"
      },
      "topicType": {
        "enum": [
          "STANDARD",
          "EVENT",
          "OFFER",
          "ALERT"
        ],
        "type": "string",
        "description": "default STANDARD"
      },
      "actionType": {
        "enum": [
          "BOOK",
          "ORDER",
          "SHOP",
          "LEARN_MORE",
          "SIGN_UP",
          "CALL"
        ],
        "type": "string",
        "description": "the button on the Post"
      },
      "couponCode": {
        "type": "string",
        "description": "OFFER only"
      },
      "locationId": {
        "type": "string",
        "description": "which listing, e.g. 'locations/123' from list_business_locations — only needed when the account manages more than one"
      },
      "languageCode": {
        "type": "string",
        "description": "BCP-47 language of the Post, default 'en'"
      },
      "redeemOnlineUrl": {
        "type": "string",
        "description": "OFFER only — this is the link Google actually uses on an offer"
      },
      "termsConditions": {
        "type": "string",
        "description": "OFFER only"
      }
    }
  }

  arguments 84 lines copy
• post_to_youtube unknown never probed

  Publish a finished video to the brand’s connected YouTube channel. Pass a Hermoso render URL (or an upload_file url for a local/external file). DEFAULTS TO UNLISTED (link-only — not on the channel, not searchable, but shareable by link AND usable as a YouTube/Google ad). Pass privacy:"public" to put it ON the channel (a public publish — confirm with the user first) or privacy:"private" for eyes-only. Do NOT use "private" for anything meant to run as an ad — private videos CANNOT be used as ads; unlisted is the ad-ready setting. SCHEDULE it with publishAt, FILE it under the right categoryId (the default 22 "People & Blogs" is wrong for most ads), SUBSCRIBER NOTIFICATIONS FOLLOW PRIVACY — a public publish announces the video to the channel’s subscribers (YouTube’s own default), while unlisted/private uploads stay quiet; pass notifySubscribers explicitly to override either way. THUMBNAIL: pass thumbnailUrl, or a frame of the video is set for free; a thumbnail YouTube refuses never fails the upload, and thumbnailNote says why. Needs a connected YouTube channel (Settings ▸ Connectors ▸ YouTube).

  mcp-tool

  1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "videoUrl"
    ],
    "properties": {
      "hook": {
        "type": "string",
        "description": "WHAT ANGLE THIS POST IS BUILT ON — the single most valuable field here, and the only moment it can ever be recorded. post_performance groups on it to answer \"which hooks work\", and it needs 5 posts sharing ONE hook before it will call anything a winner, so REUSE THE SAME WORDING across a campaign instead of rephrasing it every time. Best of all, pass a hook id from list_hooks (e.g. \"direct_callout\", \"mid_problem\", \"before_after\") — those fold onto a stable key however they are spelled, so a whole brand accumulates evidence on one row. Your own wording is fine too; it just only groups when you repeat it exactly. Omitting it means this post can never vote on which hook works."
      },
      "tags": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "up to 30 tags"
      },
      "brand": {
        "type": "string",
        "description": "WHICH BRAND this post belongs to — the id or exact name from list_brands (a workspace shared with you: its profile id). Use it whenever the account has more than one brand and you are not certain which one this connection is pinned to: it beats the pin for THIS CALL ONLY and changes nothing about the connection. A name that matches no brand, or two brands, is REFUSED and nothing is posted — never resolved to the pin, which is the account you were guarding against."
      },
      "title": {
        "type": "string",
        "description": "REQUIRED in practice — the headline every search result and the Shorts feed shows (≤100 chars); an upload with no title is refused"
      },
      "account": {
        "type": "string",
        "description": "WHICH connected account of this channel to post as — its @handle or id from list_connector_accounts. Needed only when the brand has more than one youtube account connected (several and none named is refused by name, never guessed); omit when there is one."
      },
      "privacy": {
        "enum": [
          "private",
          "unlisted",
          "public"
        ],
        "type": "string",
        "description": "default unlisted (anyone-with-link, ad-ready); public = live + searchable on the channel (confirm first); private = eyes-only (cannot run as an ad)"
      },
      "subject": {
        "type": "string",
        "description": "WHAT THIS POST IS ABOUT — the product, feature, offer or theme (e.g. \"winter coat\", \"free trial\", \"founder story\"). The second grouping axis in post_performance. Same rule as hook: reuse the exact wording so posts about one subject land in one group."
      },
      "videoUrl": {
        "type": "string",
        "description": "the video to post — a Hermoso render URL or an upload_file url"
      },
      "publishAt": {
        "type": "string",
        "description": "SCHEDULE the publish — ISO 8601, e.g. \"2026-09-01T15:00:00Z\", and it must be in the future. YouTube only allows this on a PRIVATE video and makes it PUBLIC at that moment, so pass privacy:\"private\" (or leave privacy unset) — asking for a scheduled \"unlisted\" or \"public\" post is refused rather than half-honoured."
      },
      "categoryId": {
        "type": "string",
        "description": "YouTube category id, NUMERIC — default \"22\" (People & Blogs), which is wrong for most ads. 1 Film & Animation · 2 Autos & Vehicles · 10 Music · 15 Pets & Animals · 17 Sports · 19 Travel & Events · 20 Gaming · 22 People & Blogs · 23 Comedy · 24 Entertainment · 25 News & Politics · 26 Howto & Style · 27 Education · 28 Science & Technology · 29 Nonprofits & Activism. The assignable set is region-specific, so the value is forwarded as given and YouTube has the last word."
      },
      "aiGenerated": {
        "type": "boolean",
        "description": "YouTube’s “altered or synthetic content” declaration (containsSyntheticMedia). OMIT IT and Hermoso decides from provenance: a Hermoso render is declared, a video the user uploaded through upload_file or from an external URL is NOT — real footage must not carry the label. true/false overrides."
      },
      "description": {
        "type": "string",
        "description": "REQUIRED in practice — what the video shows, a line about the brand, a link and a few #hashtags (≤5000 chars); YouTube search, suggested videos and the Shorts feed rank on it, so an upload with no description (and no caption) is refused"
      },
      "thumbnailUrl": {
        "type": "string",
        "description": "the custom thumbnail: a Hermoso-hosted image (make_thumbnail, or upload_file for the user’s own). Omit it and a representative frame of the video is set, free; \"auto\" keeps YouTube’s pick. Custom thumbnails need a verified channel."
      },
      "platformCover": {
        "type": "boolean",
        "description": "VIDEO COVER. Omit it (the default) and Hermoso sets the video’s best frame — the same frame as its Library thumbnail — as the cover (YouTube custom thumbnail; the same as thumbnailUrl:\"auto\" when true). true = send no cover and let the platform pick (usually the first frame). A cover you pass yourself always wins."
      },
      "notifySubscribers": {
        "type": "boolean",
        "description": "THE DEFAULT FOLLOWS PRIVACY. privacy:\"public\" NOTIFIES the channel's subscribers — that is YouTube's own default and normally what someone publishing publicly wants. privacy:\"unlisted\" and \"private\" do NOT: the video is not on the channel, so announcing it is nonsense, and a blast to somebody's whole subscriber list cannot be undone. A scheduled publish (publishAt) is PRIVATE at upload, so it does not notify either — pass true to announce one. An explicit value ALWAYS wins in both directions: true announces an unlisted/private upload, false publishes publicly and quietly. The reply reports which way it went and why."
      }
    }
  }

  arguments 77 lines copy
• post_to_tiktok unknown never probed

  Publish to the user’s connected TikTok account — a finished VIDEO, or a PHOTO POST (TikTok’s photo/slideshow format). A photo post carries 1 to 35 images and ONE image is simply a one-slide photo post, so there is nothing special to do for a single picture: pass imageUrls, in the order the slides should appear, and optionally coverIndex. Pass videoUrl for a video. Never pass both — TikTok has no mixed post. TWO destinations either way: destination:"post" puts it LIVE on their profile now — that requires `privacy`, and you must call tiktok_creator_info first, show the creator’s real privacy options and get an explicit yes before calling. destination:"draft" (the default, and the safer one) sends it to TikTok for the user to finish and post themselves from the app. Pass Hermoso render URLs (or upload_file urls for local/external files). Needs TikTok connected (Settings ▸ Connectors ▸ TikTok).

  mcp-tool

  1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "hook": {
        "type": "string",
        "description": "WHAT ANGLE THIS POST IS BUILT ON — the single most valuable field here, and the only moment it can ever be recorded. post_performance groups on it to answer \"which hooks work\", and it needs 5 posts sharing ONE hook before it will call anything a winner, so REUSE THE SAME WORDING across a campaign instead of rephrasing it every time. Best of all, pass a hook id from list_hooks (e.g. \"direct_callout\", \"mid_problem\", \"before_after\") — those fold onto a stable key however they are spelled, so a whole brand accumulates evidence on one row. Your own wording is fine too; it just only groups when you repeat it exactly. Omitting it means this post can never vote on which hook works."
      },
      "brand": {
        "type": "string",
        "description": "WHICH BRAND this post belongs to — the id or exact name from list_brands (a workspace shared with you: its profile id). Use it whenever the account has more than one brand and you are not certain which one this connection is pinned to: it beats the pin for THIS CALL ONLY and changes nothing about the connection. A name that matches no brand, or two brands, is REFUSED and nothing is posted — never resolved to the pin, which is the account you were guarding against."
      },
      "title": {
        "type": "string",
        "description": "the caption — hashtags go here (video ≤2200 chars, photo post ≤4000)"
      },
      "account": {
        "type": "string",
        "description": "WHICH connected account of this channel to post as — its @handle or id from list_connector_accounts. Needed only when the brand has more than one tiktok account connected (several and none named is refused by name, never guessed); omit when there is one."
      },
      "privacy": {
        "enum": [
          "PUBLIC_TO_EVERYONE",
          "MUTUAL_FOLLOW_FRIENDS",
          "FOLLOWER_OF_CREATOR",
          "SELF_ONLY"
        ],
        "type": "string",
        "description": "REQUIRED for destination:\"post\", for photos and video alike. Must be one the creator actually allows — read them from tiktok_creator_info, never guess."
      },
      "subject": {
        "type": "string",
        "description": "WHAT THIS POST IS ABOUT — the product, feature, offer or theme (e.g. \"winter coat\", \"free trial\", \"founder story\"). The second grouping axis in post_performance. Same rule as hook: reuse the exact wording so posts about one subject land in one group."
      },
      "videoUrl": {
        "type": "string",
        "description": "the video to post — a Hermoso render URL or an upload_file url. Omit for a photo post."
      },
      "imageUrls": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "a PHOTO POST: 1–35 image URLs in slide order. One url = a single-image photo post. Do not combine with videoUrl."
      },
      "yourBrand": {
        "type": "boolean",
        "description": "discloses that this promotes the creator’s own brand"
      },
      "coverIndex": {
        "type": "number",
        "description": "photo posts: which slide is the cover, 0-based. Default 0 (the first slide)."
      },
      "photoTitle": {
        "type": "string",
        "description": "photo posts only: a short title above the caption (≤90 chars). Defaults to the caption’s first line."
      },
      "aiGenerated": {
        "type": "boolean",
        "description": "TikTok’s is_aigc AI-generated-content label (video posts). OMIT IT and Hermoso decides from provenance: a Hermoso render is declared, a video that came through upload_file or an external URL (the user’s own footage) is NOT. true/false overrides."
      },
      "destination": {
        "enum": [
          "post",
          "draft"
        ],
        "type": "string",
        "description": "\"post\" = live on the profile now (needs privacy + an explicit user yes); \"draft\" = to TikTok for the user to review and post themselves. Default \"draft\"."
      },
      "disableDuet": {
        "type": "boolean",
        "description": "video only — TikTok has no duet on a photo post"
      },
      "autoAddMusic": {
        "type": "boolean",
        "description": "photo posts only: let TikTok add a recommended track (default true — a silent slideshow reads as broken)"
      },
      "disableStitch": {
        "type": "boolean",
        "description": "video only — TikTok has no stitch on a photo post"
      },
      "platformCover": {
        "type": "boolean",
        "description": "VIDEO COVER. Omit it (the default) and Hermoso sets the video’s best frame — the same frame as its Library thumbnail — as the cover (TikTok video_cover_timestamp_ms, on a direct post — a draft takes no cover, you pick it in the TikTok app). true = send no cover and let the platform pick (usually the first frame). A cover you pass yourself always wins."
      },
      "brandedContent": {
        "type": "boolean",
        "description": "discloses a paid partnership — cannot be combined with SELF_ONLY privacy"
      },
      "disableComment": {
        "type": "boolean"
      },
      "coverTimestampMs": {
        "type": "number",
        "description": "video only: which frame to use as the cover, in ms"
      }
    }
  }

  arguments 98 lines copy
• publish_to_shopify_product unknown never probed

  Attach a finished image to one of the merchant's Shopify product listings, as product media. Pass productId (from list_shopify_products — the gid://shopify/Product/… form) and a PUBLIC https imageUrl, which is what every Hermoso render returns. Shopify fetches the image server-side and processes it asynchronously, so the media can come back status PROCESSING and appear on the listing a moment later — that is success, not a failure. Only works for accounts created by installing Hermoso from the Shopify App Store. Free — the render was already paid for.

  mcp-tool

  12345678910111213141516171819202122

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "productId",
      "imageUrl"
    ],
    "properties": {
      "alt": {
        "type": "string",
        "description": "alt text for accessibility and SEO; defaults to a generic credit"
      },
      "imageUrl": {
        "type": "string",
        "description": "any public https image URL — a Hermoso render works, and so does ANY file of your own brought in with upload_file"
      },
      "productId": {
        "type": "string",
        "description": "gid://shopify/Product/… from list_shopify_products"
      }
    }
  }

  arguments 22 lines copy
• list_linkedin_pages unknown never probed

  List the LinkedIn COMPANY PAGES the connected account administers — id, name and the role held on each. ALWAYS call this before post_to_linkedin_page when there is more than one Page: publishing to the wrong company Page is a public mistake and Hermoso never chooses for the user. If it comes back empty, the account holds no Page admin role, or LinkedIn has not granted this app the organization scopes — say that plainly rather than guessing an id. Read-only, free.

  mcp-tool

  12345

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {}
  }

  arguments 5 lines copy
• post_to_linkedin_page unknown never probed

  Publish a post to one of the user’s LinkedIn COMPANY PAGES — text, plus optionally an image, a video, a 2–20 image CAROUSEL (LinkedIn calls it a MultiImage post; pass the slides in order as imageUrls[]), or a LINK POST with a real preview card (linkUrl). USE linkUrl WHENEVER THE POINT OF THE POST IS A LINK: LinkedIn disables URL scraping for API partners, so a url sitting in the text renders as plain text with no card, and the card’s title, description and image only exist if you pass linkTitle / linkDescription / linkThumbnailUrl — read them off the page and supply them. The media need not be a Hermoso render — it must be Hermoso-HOSTED because we upload the bytes to LinkedIn ourselves, and upload_file turns ANY file the user already has into such a URL. ORGANIC CAROUSELS ARE COMPANY-PAGE ONLY — a personal profile cannot publish one and is refused by name, so send a deck here rather than to post_to_linkedin. This is a DIFFERENT thing from post_to_linkedin, which publishes to the person’s own profile: pick the one the user actually asked for and never substitute. organizationId comes from list_linkedin_pages; omit it only when the account administers exactly one Page. This PUBLISHES immediately and PUBLICLY — ALWAYS show the user the exact text and get an explicit yes BEFORE calling. A VIDEO POST CAN CARRY CAPTIONS AND ITS OWN COVER, and both are attached only during the upload: pass captionsSrt (SubRip content — LinkedIn is watched with the sound off) and videoThumbnailUrl (otherwise LinkedIn picks a frame for you). LinkedIn does NOT allow the image, video, captions or thumbnail of a published post to be swapped afterwards, so get all of that right first (the copy can still be edited with manage_linkedin_post).

  mcp-tool

  123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "text"
    ],
    "properties": {
      "hook": {
        "type": "string",
        "description": "WHAT ANGLE THIS POST IS BUILT ON — the single most valuable field here, and the only moment it can ever be recorded. post_performance groups on it to answer \"which hooks work\", and it needs 5 posts sharing ONE hook before it will call anything a winner, so REUSE THE SAME WORDING across a campaign instead of rephrasing it every time. Best of all, pass a hook id from list_hooks (e.g. \"direct_callout\", \"mid_problem\", \"before_after\") — those fold onto a stable key however they are spelled, so a whole brand accumulates evidence on one row. Your own wording is fine too; it just only groups when you repeat it exactly. Omitting it means this post can never vote on which hook works."
      },
      "text": {
        "type": "string",
        "description": "the post text"
      },
      "brand": {
        "type": "string",
        "description": "WHICH BRAND this post belongs to — the id or exact name from list_brands (a workspace shared with you: its profile id). Use it whenever the account has more than one brand and you are not certain which one this connection is pinned to: it beats the pin for THIS CALL ONLY and changes nothing about the connection. A name that matches no brand, or two brands, is REFUSED and nothing is posted — never resolved to the pin, which is the account you were guarding against."
      },
      "title": {
        "type": "string",
        "description": "video title"
      },
      "altText": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        ],
        "description": "accessibility alt text (max 4086 characters, ~120 recommended). A STRING describes every image; an ARRAY describes each slide of a multi-image post separately, in slide order — LinkedIn stores altText per image, and their own sample request carries a different one on each. Not available on a PERSONAL-profile post: LinkedIn’s member posting API has no alt-text field at all."
      },
      "linkUrl": {
        "type": "string",
        "description": "publish a LINK POST — LinkedIn renders a real preview card for this URL instead of leaving a bare link in the text. Mutually exclusive with imageUrl / videoUrl / imageUrls: LinkedIn’s content field is a union, so combining them is refused by name rather than one being dropped."
      },
      "subject": {
        "type": "string",
        "description": "WHAT THIS POST IS ABOUT — the product, feature, offer or theme (e.g. \"winter coat\", \"free trial\", \"founder story\"). The second grouping axis in post_performance. Same rule as hook: reuse the exact wording so posts about one subject land in one group."
      },
      "imageUrl": {
        "type": "string",
        "description": "a Hermoso-hosted image URL — a render (list_library), or ANY image of the user’s own passed through upload_file first. An arbitrary external host is refused."
      },
      "videoUrl": {
        "type": "string",
        "description": "a Hermoso-hosted video URL — a render, or the user’s own footage via upload_file. LinkedIn processes it before publishing, which takes a minute."
      },
      "imageUrls": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "CAROUSEL — an ORDERED list of image (and, where the channel allows, video) URLs published as ONE post the viewer swipes through. THIS IS NOT “post several” — it is a single post with several slides, which is what a multi-slide creative (a listicle, a “1/6 · SWIPE” deck) actually needs; publishing only its first slide tells the viewer to swipe at something that cannot. The ORDER is the product. Limits per channel: Instagram 2–10 (images, videos or a mix), Threads 2–20 (mix allowed), Facebook 2+ (Meta publishes no documented maximum; Hermoso caps the upload fan-out at 30 and says so), LinkedIn company Pages 2–20 (images only), Pinterest 2–5 (images only), TikTok up to 35. One url here is simply an ordinary single post. Anything a channel cannot do is REFUSED with the real reason — nothing is ever quietly downgraded to one slide."
      },
      "linkTitle": {
        "type": "string",
        "description": "the headline ON the preview card. LINKEDIN NEVER SCRAPES THE PAGE — their Posts API disables URL scraping for API partners outright — so if you do not pass this the card renders UNLABELLED. Fetch the page’s own title and pass it."
      },
      "visibility": {
        "enum": [
          "PUBLIC",
          "CONNECTIONS"
        ],
        "type": "string",
        "description": "default PUBLIC"
      },
      "captionsSrt": {
        "type": "string",
        "description": "CLOSED CAPTIONS for a videoUrl post — the SubRip (.srt) CONTENT itself, cue numbers and `00:00:00,000 --> 00:00:02,000` timing lines included, NOT a URL and NOT the plain script (a file with no timings is refused, because LinkedIn would accept it and then silently never show it). Most of LinkedIn is watched with the sound off, so an uncaptioned video is one most of the feed never hears. LinkedIn allows ONE caption file per video and ENGLISH ONLY; it can be attached only WHILE the video is uploaded, never added to a published post; and it is processed asynchronously, so the reply confirms it was UPLOADED and never that it is visible yet. Requires videoUrl — passing it on an image, carousel or link post is refused by name."
      },
      "platformCover": {
        "type": "boolean",
        "description": "VIDEO COVER. Omit it (the default) and Hermoso sets the video’s best frame — the same frame as its Library thumbnail — as the cover (LinkedIn’s video thumbnail upload). true = send no cover and let the platform pick (usually the first frame). A cover you pass yourself always wins."
      },
      "allowDuplicate": {
        "type": "boolean",
        "description": "post it even though an identical post was just made or attempted. Only pass this when the user genuinely wants the same thing posted twice, or when you have LOOKED at the account and confirmed a timed-out attempt did not land."
      },
      "idempotencyKey": {
        "type": "string",
        "description": "SAFE RETRIES. Publishing can take minutes (a video upload, a carousel of ten slides) and a transport can time out while the post SUCCEEDS — retrying blind is how the same thing gets posted twice. Pass any stable string here and a repeat of the SAME publish returns the ORIGINAL post id instead of posting again (24h). You do not have to: an identical publish is auto-recognised for 10 minutes anyway. If a call times out or errors ambiguously, CALL AGAIN WITH THE SAME KEY — that is the safe move, and it will either report the original post or publish it for the first time. It never posts twice."
      },
      "organizationId": {
        "type": "string",
        "description": "numeric Page id from list_linkedin_pages"
      },
      "targetAudience": {
        "type": "object",
        "properties": {
          "degrees": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "industries": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "seniorities": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "geoLocations": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "jobFunctions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "fieldsOfStudy": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "organizations": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "staffCountRanges": {
            "type": "array",
            "items": {
              "enum": [
                "SIZE_1",
                "SIZE_2_TO_10",
                "SIZE_11_TO_50",
                "SIZE_51_TO_200",
                "SIZE_201_TO_500",
                "SIZE_501_TO_1000",
                "SIZE_1001_TO_5000",
                "SIZE_5001_TO_10000",
                "SIZE_10001_OR_MORE"
              ],
              "type": "string"
            }
          }
        },
        "description": "LINKEDIN COMPANY PAGE POST ONLY — show the post only to Page followers matching these facets (URNs or bare numeric ids; search_linkedin_ads_targeting finds them). LinkedIn requires the matching audience to be over 300 followers and refuses a smaller one. Personal-profile posts cannot be targeted."
      },
      "linkDescription": {
        "type": "string",
        "description": "the sub-line on the preview card. Same rule as linkTitle: absent means blank, because LinkedIn will not fetch it."
      },
      "linkThumbnailUrl": {
        "type": "string",
        "description": "a Hermoso-hosted image used as the card’s picture (uploaded to LinkedIn for you). Without it the card has no image."
      },
      "videoThumbnailUrl": {
        "type": "string",
        "description": "the COVER IMAGE for a videoUrl post — a Hermoso-hosted image (a render, or any picture of the user’s via upload_file). Without it LinkedIn adds a system-generated thumbnail, which on an ad is usually whatever the first frame happens to be. Like captions this can only be set WHILE the video is uploaded, never afterwards. Requires videoUrl. This is NOT linkThumbnailUrl, which is the picture on a link-preview card."
      }
    }
  }

  arguments 171 lines copy
• list_linkedin_lead_forms unknown never probed

  The LEAD GEN FORMS a LinkedIn company Page or ad account owns — id, name, state, version and the fields each one asks for (firstName, email, company …). Forms are created in Campaign Manager or on the Page; this API reads them and cannot create one. If it answers that the connection must be reconnected, say exactly that: the lead-sync permission is granted at authorise time. Read-only, free.

  mcp-tool

  1234567891011121314

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "pageId": {
        "type": "string",
        "description": "the company Page that owns the form — from list_linkedin_pages; omit when one Page is shared"
      },
      "adAccountId": {
        "type": "string",
        "description": "read forms owned by an AD ACCOUNT instead of a Page"
      }
    }
  }

  arguments 14 lines copy
• list_linkedin_leads unknown never probed

  The LEADS a LinkedIn lead gen form collected — every response with its answers keyed by field (firstName, lastName, email, company, …), the campaign and creative that produced it, the consents ticked, and whether it was a test lead. Newest first. Filter by formId, a since/until window (ISO date or epoch ms — LinkedIn takes epoch), or testLeadsOnly. THIS IS PERSONAL DATA: show it to the user, hand it to the CRM they name, never repeat it into a post or an unrelated tool. Pass start for the next page. Read-only, free.

  mcp-tool

  123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "limit": {
        "type": "number",
        "description": "per page, max 100"
      },
      "since": {
        "type": "string",
        "description": "ISO date or epoch milliseconds"
      },
      "start": {
        "type": "number",
        "description": "offset for the next page"
      },
      "until": {
        "type": "string"
      },
      "formId": {
        "type": "string",
        "description": "only this form (from list_linkedin_lead_forms)"
      },
      "pageId": {
        "type": "string",
        "description": "the company Page that owns the form — from list_linkedin_pages; omit when one Page is shared"
      },
      "leadType": {
        "enum": [
          "SPONSORED",
          "COMPANY",
          "EVENT",
          "ORGANIZATION_PRODUCT"
        ],
        "type": "string",
        "description": "defaults by owner: SPONSORED for an ad account, COMPANY (organic Page form) for a Page; EVENT for event forms. LinkedIn refuses SPONSORED on a Page owner"
      },
      "adAccountId": {
        "type": "string",
        "description": "read forms owned by an AD ACCOUNT instead of a Page"
      },
      "formVersion": {
        "type": "number",
        "description": "default 1"
      },
      "testLeadsOnly": {
        "type": "boolean",
        "description": "true returns ONLY test submissions"
      }
    }
  }

  arguments 51 lines copy
• get_linkedin_lead unknown never probed

  One LinkedIn lead by id (from list_linkedin_leads), with every answer named by field. Personal data — show, never republish. Read-only, free.

  mcp-tool

  1234567891011121314151617181920

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "leadId"
    ],
    "properties": {
      "leadId": {
        "type": "string"
      },
      "pageId": {
        "type": "string",
        "description": "the company Page that owns the form — from list_linkedin_pages; omit when one Page is shared"
      },
      "adAccountId": {
        "type": "string",
        "description": "read forms owned by an AD ACCOUNT instead of a Page"
      }
    }
  }

  arguments 20 lines copy
• subscribe_linkedin_leads unknown never probed

  Have LinkedIn push every new lead to Hermoso the moment it is submitted, and optionally relay each event on to the user’s own CRM. THE WEBHOOK LINKEDIN VALIDATES IS ALWAYS HERMOSO’S OWN: LinkedIn challenges it with our app secret (and re-challenges every ~2 hours), which no CRM, Zapier or Make endpoint can answer — so never promise a customer URL as the LinkedIn webhook. Pass forwardTo (public HTTPS) to have Hermoso relay each lead event there; leave it off to keep events in Hermoso only (list_linkedin_lead_events). The reply is read back from LinkedIn, not from the 201. Leads stay readable with list_linkedin_leads either way. Free.

  mcp-tool

  12345678910111213141516171819202122232425262728

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "pageId": {
        "type": "string",
        "description": "the company Page that owns the form — from list_linkedin_pages; omit when one Page is shared"
      },
      "leadType": {
        "enum": [
          "SPONSORED",
          "COMPANY",
          "EVENT",
          "ORGANIZATION_PRODUCT"
        ],
        "type": "string",
        "description": "defaults by owner: SPONSORED for an ad account, COMPANY for a Page"
      },
      "forwardTo": {
        "type": "string",
        "description": "optional public HTTPS URL Hermoso relays each lead event to (a CRM, Zapier, Make)"
      },
      "adAccountId": {
        "type": "string",
        "description": "read forms owned by an AD ACCOUNT instead of a Page"
      }
    }
  }

  arguments 28 lines copy
• list_linkedin_lead_events unknown never probed

  The lead events LinkedIn has PUSHED to Hermoso for this brand (new lead / deleted lead, with the form and the lead id), newest first. Empty means none have arrived, not that none exist — list_linkedin_leads reads every lead regardless, and subscribe_linkedin_leads is what starts delivery. Read a lead’s answers with get_linkedin_lead. Read-only, free.

  mcp-tool

  123456789

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "limit": {
        "type": "number"
      }
    }
  }

  arguments 9 lines copy
• list_linkedin_lead_subscriptions unknown never probed

  The lead notification webhooks registered on a LinkedIn Page or ad account, with the id delete_linkedin_lead_subscription takes. Read-only, free.

  mcp-tool

  1234567891011121314151617

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "pageId": {
        "type": "string",
        "description": "the company Page that owns the form — from list_linkedin_pages; omit when one Page is shared"
      },
      "leadType": {
        "type": "string"
      },
      "adAccountId": {
        "type": "string",
        "description": "read forms owned by an AD ACCOUNT instead of a Page"
      }
    }
  }

  arguments 17 lines copy
• delete_linkedin_lead_subscription unknown never probed

  Remove a lead notification webhook (subscriptionId from list_linkedin_lead_subscriptions). Leads themselves are unaffected and stay readable; only the real-time delivery stops. Read back from LinkedIn. Free.

  mcp-tool

  1234567891011121314151617181920

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "subscriptionId"
    ],
    "properties": {
      "pageId": {
        "type": "string",
        "description": "the company Page that owns the form — from list_linkedin_pages; omit when one Page is shared"
      },
      "adAccountId": {
        "type": "string",
        "description": "read forms owned by an AD ACCOUNT instead of a Page"
      },
      "subscriptionId": {
        "type": "string"
      }
    }
  }

  arguments 20 lines copy
• save_to_drive unknown never probed

  Save a Hermoso render — or ANY file — into the user’s connected Google Drive. Pass a Hermoso render URL as url (or urls[] for several); for a local/external file, call upload_file first and pass the url it returns. Optional folder (created if new) + name. Returns the Drive file(s) with a webViewLink. Needs Google Drive connected (Settings ▸ Connectors ▸ Google Drive — one connection covers Drive, Sheets and Docs). NOTE: Hermoso uses the drive.file scope, so it reaches ONLY the files it created plus any the user explicitly handed over with the Google file picker in the app — never their whole Drive.

  mcp-tool

  12345678910111213141516171819202122232425

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "url": {
        "type": "string",
        "description": "a single Hermoso render URL to save"
      },
      "name": {
        "type": "string",
        "description": "file name (single save)"
      },
      "urls": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "several render URLs (up to 20) to save in one call"
      },
      "folder": {
        "type": "string",
        "description": "Drive folder name to save into (created if new)"
      }
    }
  }

  arguments 25 lines copy
• import_from_cloud unknown never probed

  Pull the files in a Google Drive or OneDrive FOLDER into this brand's Library, so they can be used like anything rendered here — published, scheduled, cloned, used as a product photo or a reference. Hermoso downloads each file with the user's own connected account (a Drive/OneDrive file is not public, so this is the only way in) and stores a durable Hermoso url for each. Give `folderId` from list_drive_files / list_onedrive_files with onlyFolders — omit it for the root. GOOGLE DRIVE ONLY SHOWS WHAT THE USER HANDED OVER: our Drive scope is `drive.file`, so Hermoso can see the files and folders it created plus the ones the user picked with the Google picker in the app, and NEVER their whole Drive — if a folder comes back empty, that is the answer, and the user picks it in the app once to make it reachable. OneDrive has no such limit. SUBFOLDERS ARE NOT WALKED and Google-native docs (Docs/Sheets/Slides) have no file to download: both are reported back BY NAME rather than silently dropped, along with anything too large or unreadable, so you can tell the user exactly what did and did not come across.

  mcp-tool

  12345678910111213141516171819202122232425

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "provider"
    ],
    "properties": {
      "limit": {
        "type": "number",
        "description": "how many files to bring across in this call (default 10, max 25). Anything over the limit is listed as skipped so you know what is left."
      },
      "folderId": {
        "type": "string",
        "description": "the folder to import, from list_drive_files / list_onedrive_files (onlyFolders:true). Omit for the root of the drive."
      },
      "provider": {
        "enum": [
          "drive",
          "onedrive"
        ],
        "type": "string",
        "description": "which cloud — `drive` is Google Drive, `onedrive` is Microsoft OneDrive"
      }
    }
  }

  arguments 25 lines copy
• list_drive_files unknown never probed

  List the Google Drive files & folders Hermoso can reach — the ones it created, plus any the user handed over with the Google file picker in the app (the drive.file scope exposes nothing else, never their entire Drive). This is how you find the id of a file the user picked. Filter by query (name contains …), folderId (contents of a folder), or onlyFolders:true. Paginate with pageToken. Read-only.

  mcp-tool

  123456789101112131415161718192021222324252627282930

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "query": {
        "type": "string",
        "description": "only files whose name contains this"
      },
      "folderId": {
        "type": "string",
        "description": "list the contents of this folder id"
      },
      "pageSize": {
        "type": "number",
        "description": "rows per page (1–200, default 50)"
      },
      "pageToken": {
        "type": "string",
        "description": "cursor from a previous call"
      },
      "onlyFolders": {
        "type": "boolean",
        "description": "list folders only"
      },
      "includeTrashed": {
        "type": "boolean",
        "description": "include trashed files (default false)"
      }
    }
  }

  arguments 30 lines copy
• get_drive_file unknown never probed

  Fetch one Drive file’s metadata — name, type, size, modified time, a webViewLink to open it and a webContentLink to download it. Pass fileId (from list_drive_files). Read-only.

  mcp-tool

  12345678910111213

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "fileId"
    ],
    "properties": {
      "fileId": {
        "type": "string",
        "description": "the Drive file id (from list_drive_files)"
      }
    }
  }

  arguments 13 lines copy
• update_drive_file unknown never probed

  Update a Drive file: rename (name), move it into a folder (moveToFolderId, optionally removeFromFolderId to move OUT of the old one), or trash / untrash it (trash:true|false). Pass fileId (from list_drive_files). To delete permanently, use delete_drive_file.

  mcp-tool

  1234567891011121314151617181920212223242526272829

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "fileId"
    ],
    "properties": {
      "name": {
        "type": "string",
        "description": "new name"
      },
      "trash": {
        "type": "boolean",
        "description": "true → move to Trash; false → restore from Trash"
      },
      "fileId": {
        "type": "string",
        "description": "the Drive file id"
      },
      "moveToFolderId": {
        "type": "string",
        "description": "folder id to move the file into (from create_drive_folder / list_drive_files)"
      },
      "removeFromFolderId": {
        "type": "string",
        "description": "the old parent folder id to remove (when moving)"
      }
    }
  }

  arguments 29 lines copy
• delete_drive_file unknown never probed

  Delete a Drive file. By default it goes to Trash (recoverable); pass permanent:true to delete it forever. Pass fileId (from list_drive_files) + confirm:true. Irreversible when permanent — confirm with the user first.

  mcp-tool

  123456789101112131415161718192021

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "fileId"
    ],
    "properties": {
      "fileId": {
        "type": "string",
        "description": "the Drive file id"
      },
      "confirm": {
        "type": "boolean",
        "description": "REQUIRED true"
      },
      "permanent": {
        "type": "boolean",
        "description": "true = delete forever; default trashes (recoverable)"
      }
    }
  }

  arguments 21 lines copy
• create_drive_folder unknown never probed

  Create a folder in the user’s Google Drive (optionally nested under parentId) to organize saved files. Returns the folder id + webViewLink. Use that ID as update_drive_file’s moveToFolderId or as parentId for a nested folder. NOTE: save_to_drive’s `folder` is a NAME, not this id — it find-or-creates a folder by that name, so pass the folder NAME there (or omit and just save, then move with update_drive_file).

  mcp-tool

  1234567891011121314151617

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "name"
    ],
    "properties": {
      "name": {
        "type": "string",
        "description": "folder name"
      },
      "parentId": {
        "type": "string",
        "description": "parent folder id for a nested folder (default: Drive root)"
      }
    }
  }

  arguments 17 lines copy
• create_sheet unknown never probed

  Create a new Google Spreadsheet in the user’s Drive and optionally fill it with rows — e.g. export a swipefile, ad list, or performance report. Pass rows as an array of row arrays (first row = headers). Returns the spreadsheet id + URL. Needs Google Drive connected (Settings ▸ Connectors ▸ Google Drive — one connection covers Drive, Sheets and Docs).

  mcp-tool

  123456789101112131415161718192021222324252627282930

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "rows": {
        "type": "array",
        "items": {
          "type": "array",
          "items": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "boolean"
              }
            ]
          }
        },
        "description": "rows to write — array of row arrays; first row = headers"
      },
      "title": {
        "type": "string",
        "description": "spreadsheet title"
      }
    }
  }

  arguments 30 lines copy
• append_to_sheet unknown never probed

  Append rows to a Google Sheet Hermoso can reach — one it created (pass the spreadsheetId from create_sheet) or one the user handed over with the Google file picker in the app (find its id with list_drive_files). rows = array of row arrays.

  mcp-tool

  1234567891011121314151617181920212223242526272829303132333435363738

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "spreadsheetId",
      "rows"
    ],
    "properties": {
      "rows": {
        "type": "array",
        "items": {
          "type": "array",
          "items": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "boolean"
              }
            ]
          }
        },
        "description": "rows to append — array of row arrays"
      },
      "range": {
        "type": "string",
        "description": "range to append at (default A1 / first sheet)"
      },
      "spreadsheetId": {
        "type": "string",
        "description": "the spreadsheet id from create_sheet"
      }
    }
  }

  arguments 38 lines copy
• read_sheet unknown never probed

  Read cells from a Google Sheet Hermoso can reach — one it created, or one the user handed over with the Google file picker in the app (that is how an EXISTING spreadsheet becomes readable; find its id with list_drive_files). Pass the spreadsheetId (from create_sheet) OR paste a Google Sheets URL as sheetUrl. If Google answers that the file was not found, the user has not picked it yet — ask them to pick it in the app rather than retrying. Returns a 2-D array of values.

  mcp-tool

  123456789101112131415161718

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "range": {
        "type": "string",
        "description": "A1 range, e.g. \"A1:D50\" (default A1:Z1000)"
      },
      "sheetUrl": {
        "type": "string",
        "description": "a Google Sheets URL to read — the spreadsheet id is extracted from it"
      },
      "spreadsheetId": {
        "type": "string",
        "description": "the spreadsheet id (from create_sheet)"
      }
    }
  }

  arguments 18 lines copy
• export_swipefile_deck unknown never probed

  Turn a SWIPEFILE COLLECTION into a real Google Slides deck — one slide per saved ad, carrying the creative, the brand, the ad copy, the run dates with the run length, and the platform. This is the thing a marketer actually presents to a client or a team; until now the swipefile’s only export was JSON. Returns the presentation id + URL. Creates a NEW deck every time: under the drive.file scope Hermoso can only touch files it created, so it cannot add slides to a deck the user already has. A creative whose ad-library link has expired cannot be embedded — Meta signs those URLs with a short expiry — so that slide says so in words and keeps its copy and run dates, and the reply reports how many. Needs Google Drive connected (Settings ▸ Connectors ▸ Google Drive — one connection covers Drive, Sheets, Docs and Slides).

  mcp-tool

  123456789101112131415161718

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "limit": {
        "type": "number",
        "description": "max ads to include, 1-60 (default 30)"
      },
      "title": {
        "type": "string",
        "description": "deck title (default: the collection name)"
      },
      "collection": {
        "type": "string",
        "description": "the swipefile collection to export, by name or id (default: the first collection)"
      }
    }
  }

  arguments 18 lines copy
• create_doc unknown never probed

  Create a new Google Doc in the user’s Drive with a title + optional body text — e.g. export ad copy, a creative brief, or a report. Returns the document id + URL. Needs Google Drive connected (Settings ▸ Connectors ▸ Google Drive — one connection covers Drive, Sheets and Docs).

  mcp-tool

  1234567891011121314

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "text": {
        "type": "string",
        "description": "body text to insert"
      },
      "title": {
        "type": "string",
        "description": "document title"
      }
    }
  }

  arguments 14 lines copy
• append_to_doc unknown never probed

  Append text to the end of a Google Doc Hermoso can reach — one it created (pass the documentId from create_doc) or one the user handed over with the Google file picker in the app (find its id with list_drive_files).

  mcp-tool

  123456789101112131415161718

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "documentId",
      "text"
    ],
    "properties": {
      "text": {
        "type": "string",
        "description": "text to append at the end of the doc"
      },
      "documentId": {
        "type": "string",
        "description": "the document id from create_doc"
      }
    }
  }

  arguments 18 lines copy
• read_doc unknown never probed

  Read the text of a Google Doc Hermoso can reach — one it created, or one the user handed over with the Google file picker in the app (that is how an EXISTING doc becomes readable; find its id with list_drive_files). Pass documentId (from create_doc) OR paste a Google Docs URL as docUrl. Under the drive.file scope it reaches nothing else in the user’s Drive; if Google answers that the file was not found, the user has not picked it yet — ask them to pick it in the app rather than retrying. Returns the plain text. Read-only, free.

  mcp-tool

  1234567891011121314

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "docUrl": {
        "type": "string",
        "description": "a Google Docs URL to read — the document id is extracted from it"
      },
      "documentId": {
        "type": "string",
        "description": "the document id (from create_doc)"
      }
    }
  }

  arguments 14 lines copy
• list_sheet_tabs unknown never probed

  The tabs in a Google Spreadsheet, each with its name, numeric sheetId, row/column count and position. Call this BEFORE naming a tab in update_sheet / clear_sheet_range / manage_sheet_tabs / format_sheet, and before proposing to delete one — it is how you learn what the file actually contains instead of guessing at a name. Read-only, free.

  mcp-tool

  1234567891011121314

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "sheetUrl": {
        "type": "string",
        "description": "a Google Sheets URL — the id is extracted from it"
      },
      "spreadsheetId": {
        "type": "string",
        "description": "the spreadsheet id (from create_sheet, or list_drive_files for one the user picked)"
      }
    }
  }

  arguments 14 lines copy
• update_sheet unknown never probed

  CORRECT cells in a Google Sheet — write values to an exact range, overwriting whatever is there. This is the fix append_to_sheet cannot make: appending only ever adds rows at the bottom, so without this a wrong number stays wrong forever and the only "correction" is a second row contradicting the first. Pass `range` (e.g. "B2:C5", or "Q3 Report!B2" to name a tab — list_sheet_tabs gives the names) and `values` as an array of row arrays; an anchor cell like "B2" is fine and the block is written down and right from it. Writing into EMPTY cells goes straight through. Writing OVER cells that already hold values is REFUSED first, naming exactly how many filled cells would be overwritten — show the user that, get a yes, then call again with confirm:true. The result is READ BACK from the sheet, so what you report is what the sheet now holds rather than what Google accepted.

  mcp-tool

  12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "range": {
        "type": "string",
        "description": "A1 range or anchor cell, e.g. \"B2:C5\", \"B2\", or \"Q3 Report!B2\" (default A1)"
      },
      "values": {
        "type": "array",
        "items": {
          "type": "array",
          "items": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "boolean"
              }
            ]
          }
        },
        "description": "array of row arrays to write"
      },
      "confirm": {
        "type": "boolean",
        "description": "required only when the target range already holds values"
      },
      "updates": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "range": {
              "type": "string"
            },
            "values": {
              "type": "array",
              "items": {
                "type": "array",
                "items": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "number"
                    },
                    {
                      "type": "boolean"
                    }
                  ]
                }
              }
            }
          }
        },
        "description": "write SEVERAL disjoint ranges in one call, instead of range+values"
      },
      "sheetUrl": {
        "type": "string"
      },
      "spreadsheetId": {
        "type": "string"
      },
      "valueInputOption": {
        "enum": [
          "USER_ENTERED",
          "RAW"
        ],
        "type": "string",
        "description": "USER_ENTERED (default) parses formulas, dates and numbers the way typing them would; RAW stores every value as literal text"
      }
    }
  }

  arguments 79 lines copy
• clear_sheet_range unknown never probed

  Empty a range of cells in a Google Sheet, leaving the rows themselves in place. DESTRUCTIVE: call it WITHOUT confirm first and nothing is cleared — you get back the real number of filled cells in that exact range. Show the user that number, get an unambiguous yes, then call again with confirm:true AND confirmCells set to it. The echo is not ceremony: it is what catches naming A1:Z1000 when you meant A1:Z10, which is the mistake that actually happens. There is deliberately NO default range. The clear is read back and reported as confirmed only if the range really is empty afterwards. To remove a whole tab instead, use manage_sheet_tabs.

  mcp-tool

  1234567891011121314151617181920212223242526

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "range"
    ],
    "properties": {
      "range": {
        "type": "string",
        "description": "the range to clear, e.g. \"A2:D50\" or \"Sheet1!A2:D50\""
      },
      "confirm": {
        "type": "boolean"
      },
      "sheetUrl": {
        "type": "string"
      },
      "confirmCells": {
        "type": "number",
        "description": "echo back the filled-cell count the unconfirmed call reported"
      },
      "spreadsheetId": {
        "type": "string"
      }
    }
  }

  arguments 26 lines copy
• manage_sheet_tabs unknown never probed

  Add, rename or delete a tab in a Google Spreadsheet. action:"add" + title · action:"rename" + tab + newTitle · action:"delete" + tab. Name the tab by its TITLE or its numeric sheetId (list_sheet_tabs gives both); an unknown tab is refused with the real list rather than a Google error nobody can map back. DELETING a tab destroys everything on it: call it without confirm first to get the filled-cell count, then confirm:true + confirmCells. Google does not allow removing the LAST remaining tab in a file, and that is refused by name with the way out (clear it, or delete the whole file with delete_drive_file). Every action is read back from the spreadsheet before it is reported as done.

  mcp-tool

  1234567891011121314151617181920212223242526272829303132333435363738394041

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "action"
    ],
    "properties": {
      "tab": {
        "type": "string",
        "description": "which tab — its title or numeric sheetId (rename / delete)"
      },
      "title": {
        "type": "string",
        "description": "the name for the new tab (action:\"add\")"
      },
      "action": {
        "enum": [
          "add",
          "rename",
          "delete"
        ],
        "type": "string"
      },
      "confirm": {
        "type": "boolean"
      },
      "newTitle": {
        "type": "string",
        "description": "what to rename the tab to (action:\"rename\")"
      },
      "sheetUrl": {
        "type": "string"
      },
      "confirmCells": {
        "type": "number"
      },
      "spreadsheetId": {
        "type": "string"
      }
    }
  }

  arguments 41 lines copy
• format_sheet unknown never probed

  Make an exported sheet readable: bold the header row, FREEZE it so it stays visible while scrolling, and auto-size the columns so nothing is cut off. Worth calling right after create_sheet — a raw export with unsized columns and a header that scrolls away is the difference between a spreadsheet someone reads and one they close. Changes no cell VALUE, so it is never gated. The defaults do all three on the first tab; pass `tab` to pick another, freezeRows:0 to skip freezing, boldHeader:false or autoResize:false to skip those.

  mcp-tool

  1234567891011121314151617181920212223242526

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "tab": {
        "type": "string",
        "description": "tab title or numeric sheetId (default: the first tab)"
      },
      "sheetUrl": {
        "type": "string"
      },
      "autoResize": {
        "type": "boolean"
      },
      "boldHeader": {
        "type": "boolean"
      },
      "freezeRows": {
        "type": "number",
        "description": "how many top rows to freeze (default 1, 0 = none)"
      },
      "spreadsheetId": {
        "type": "string"
      }
    }
  }

  arguments 26 lines copy
• update_doc unknown never probed

  EDIT a Google Doc — the correction append_to_doc cannot make, which until now meant a doc could only ever grow and a wrong line stayed in it forever. Two shapes: `replacements:[{find, replace}]` rewrites specific text wherever it appears (call read_doc first and match the text EXACTLY; matchCase:false ignores case), or `rewrite:"…"` replaces the ENTIRE body (rewrite:"" empties it). Find/replace runs immediately and REPORTS how many occurrences changed — zero matches is reported as a FAILURE to match, never as a quiet success, because a text edit that silently does nothing is worse than one that visibly fails. A whole-body rewrite is destructive: call it without confirm first to get the character count, then confirm:true + confirmCells. Both are index-free by design — an agent cannot reliably compute Google’s character offsets, and a wrong offset deletes the wrong sentence.

  mcp-tool

  12345678910111213141516171819202122232425262728293031323334353637383940414243444546

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "docUrl": {
        "type": "string",
        "description": "a Google Docs URL — the id is extracted from it"
      },
      "confirm": {
        "type": "boolean"
      },
      "rewrite": {
        "type": "string",
        "description": "replace the WHOLE body with this text (\"\" empties the doc)"
      },
      "documentId": {
        "type": "string",
        "description": "the document id (from create_doc, or list_drive_files for one the user picked)"
      },
      "confirmCells": {
        "type": "number",
        "description": "echo back the character count the unconfirmed call reported (rewrite only)"
      },
      "replacements": {
        "type": "array",
        "items": {
          "type": "object",
          "required": [
            "find"
          ],
          "properties": {
            "find": {
              "type": "string"
            },
            "replace": {
              "type": "string"
            },
            "matchCase": {
              "type": "boolean"
            }
          }
        },
        "description": "find/replace pairs, applied in order"
      }
    }
  }

  arguments 46 lines copy
• save_to_onedrive unknown never probed

  Save a Hermoso render — or ANY file — into the user’s connected Microsoft OneDrive. Pass a Hermoso render URL as url (or urls[] for several); for a local/external file, call upload_file first and pass the url it returns. Optional folder (created if new) + name. Returns the OneDrive file(s) with a webViewLink. Needs OneDrive connected (Settings ▸ Connectors ▸ OneDrive).

  mcp-tool

  12345678910111213141516171819202122232425

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "url": {
        "type": "string",
        "description": "a single Hermoso render URL to save"
      },
      "name": {
        "type": "string",
        "description": "file name (single save)"
      },
      "urls": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "several render URLs (up to 20) to save in one call"
      },
      "folder": {
        "type": "string",
        "description": "OneDrive folder name to save into (created if new)"
      }
    }
  }

  arguments 25 lines copy
• list_onedrive_files unknown never probed

  List files & folders in the user’s OneDrive — the root by default, a folder’s contents (folderId), or a name search (query). onlyFolders:true lists folders only. Paginate with pageToken (the cursor from a previous call). Read-only.

  mcp-tool

  1234567891011121314151617181920212223242526

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "query": {
        "type": "string",
        "description": "search — only items whose name matches this"
      },
      "folderId": {
        "type": "string",
        "description": "list the contents of this folder id"
      },
      "pageSize": {
        "type": "number",
        "description": "rows per page (1–200, default 50)"
      },
      "pageToken": {
        "type": "string",
        "description": "cursor from a previous call"
      },
      "onlyFolders": {
        "type": "boolean",
        "description": "list folders only"
      }
    }
  }

  arguments 26 lines copy
• get_onedrive_file unknown never probed

  Fetch one OneDrive item’s metadata — name, type, size, modified time, a webViewLink to open it and a webContentLink to download it. Pass fileId (from list_onedrive_files). Read-only.

  mcp-tool

  12345678910111213

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "fileId"
    ],
    "properties": {
      "fileId": {
        "type": "string",
        "description": "the OneDrive item id (from list_onedrive_files)"
      }
    }
  }

  arguments 13 lines copy
• update_onedrive_file unknown never probed

  Update a OneDrive item: rename (name) and/or move it into a folder (moveToFolderId). Pass fileId (from list_onedrive_files). To remove an item, use delete_onedrive_file.

  mcp-tool

  123456789101112131415161718192021

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "fileId"
    ],
    "properties": {
      "name": {
        "type": "string",
        "description": "new name"
      },
      "fileId": {
        "type": "string",
        "description": "the OneDrive item id"
      },
      "moveToFolderId": {
        "type": "string",
        "description": "folder id to move the item into (from create_onedrive_folder / list_onedrive_files)"
      }
    }
  }

  arguments 21 lines copy
• delete_onedrive_file unknown never probed

  Delete a OneDrive item — it moves to the OneDrive recycle bin (recoverable there). Pass fileId (from list_onedrive_files) + confirm:true. Confirm the exact file with the user first.

  mcp-tool

  1234567891011121314151617

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "fileId"
    ],
    "properties": {
      "fileId": {
        "type": "string",
        "description": "the OneDrive item id"
      },
      "confirm": {
        "type": "boolean",
        "description": "REQUIRED true"
      }
    }
  }

  arguments 17 lines copy
• convert_onedrive_file unknown never probed

  Turn a file already in the user’s OneDrive into a PDF or a JPG — Microsoft does the conversion on its own servers, so nothing is re-encoded here and nothing is lost in a screenshot. It reads about 130 source formats, which is the point: PowerPoint and Word decks, Excel, Photoshop PSD, Illustrator AI, Sketch, 3D (fbx/glb/obj), video (mp4/mov/webm), HEIC from an iPhone, and the raw camera formats (CR2, NEF, ARW, DNG) that nothing else in this product can open. Use it to turn a client’s deck into images you can actually put in an ad, to get a usable JPG out of a designer’s PSD or a photographer’s raw file, or to hand someone a PDF of a spreadsheet. CONVERTING TO JPG REQUIRES BOTH width AND height — Microsoft refuses the call without them. The result is stored at a durable Hermoso URL you can pass straight to a render or a post; Microsoft’s own conversion link expires within minutes, so do not hand that one to anyone. Needs OneDrive connected — no new permission.

  mcp-tool

  1234567891011121314151617181920212223242526272829

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "fileId"
    ],
    "properties": {
      "width": {
        "type": "number",
        "description": "REQUIRED for jpg — output width in pixels"
      },
      "fileId": {
        "type": "string",
        "description": "the OneDrive item id, from list_onedrive_files"
      },
      "format": {
        "enum": [
          "pdf",
          "jpg"
        ],
        "type": "string",
        "description": "default pdf"
      },
      "height": {
        "type": "number",
        "description": "REQUIRED for jpg — output height in pixels"
      }
    }
  }

  arguments 29 lines copy
• create_onedrive_folder unknown never probed

  Create a folder in the user’s OneDrive (optionally nested under parentId) to organize saved files. Returns the folder id + webViewLink. Use that id as update_onedrive_file’s moveToFolderId or as parentId for a nested folder. NOTE: save_to_onedrive’s `folder` is a NAME (find-or-created), not this id.

  mcp-tool

  1234567891011121314151617

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "name"
    ],
    "properties": {
      "name": {
        "type": "string",
        "description": "folder name"
      },
      "parentId": {
        "type": "string",
        "description": "parent folder id for a nested folder (default: OneDrive root)"
      }
    }
  }

  arguments 17 lines copy
• plan_ad unknown never probed

  Creative director: turn a brand + product/brief into a finished ad CONCEPT — copy variants (headline/primary/cta) plus an image_concept.prompt OR a video_storyboard, with the resolved recipe + the model ids to render with. Renders nothing; chain its output into generate_image / generate_video. THE USER’S EXPLICIT LENGTH IS SOVEREIGN: when they name a duration ("a 30 second ad", "make it 45s"), pass it as durationSeconds — the board is then AUTHORED to that length (its scenes sum to it) and render_ad renders it as one clip or stitched acts accordingly. Leaving it out lets the planner pick its own default, which is how an explicit ask silently becomes a 15s spot. Spends credits.

  mcp-tool

  1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "product"
    ],
    "properties": {
      "hook": {
        "type": "string",
        "description": "force the VISUAL scroll-stop mechanic the opening beat is built on — a hook id from list_hooks (e.g. \"direct_callout\", \"mid_problem\", \"macro_asmr\"). Omit to let the planner pick. A hook that cannot be delivered in this brief is DROPPED with the reason rather than rendered wrongly — an on-screen-text hook on an authentic/UGC ad is the one that bites, because that register carries zero on-screen text."
      },
      "brand": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "object",
            "properties": {},
            "additionalProperties": {}
          }
        ],
        "description": "brand name, or a brand profile object {name,domain,category,palette,products,…}. OMIT to use the workspace’s SAVED brand + memory automatically (see get_brand); use draft_brand to onboard a new one"
      },
      "format": {
        "enum": [
          "auto",
          "image",
          "video"
        ],
        "type": "string",
        "description": "'image', 'video', or 'auto' when unspecified"
      },
      "recipe": {
        "type": "string",
        "description": "a recipe id from hermoso_capabilities to force an archetype"
      },
      "product": {
        "type": "string",
        "description": "what to advertise + any angle/offer the user specified"
      },
      "setting": {
        "type": "string",
        "description": "force the WHERE — a setting id from list_hooks (e.g. \"kitchen\", \"gym\", or a surreal one like \"volcano_rim\" / \"airplane_wing\", which are played 100% straight and never acknowledged). Omit for a neutral setting."
      },
      "language": {
        "type": "string",
        "description": "output language for the ad copy (e.g. Spanish) — default English"
      },
      "reference": {
        "type": "string",
        "description": "a reference to clone: an ad-library link (Facebook Ad Library, LinkedIn Ad Library, Google Ads Transparency — its real copy/advertiser are fetched) OR a VIDEO link — a TikTok, Instagram Reel, Facebook video, X post, YouTube Short/video or a direct video file — which is WATCHED first (frames + voiceover/on-screen-text transcript) so the concept keeps its hook, structure and pacing. To remake one video for this brand at its own length, clone_video is the direct tool"
      },
      "durationSeconds": {
        "type": "number",
        "description": "VIDEO ONLY — the total spot length the user explicitly asked for, in seconds, copied verbatim (30 for \"a 30 second ad\"). The planner authors the storyboard TO it: the scenes’ seconds sum to it and the script is word-budgeted for it. Supported range 4–180; anything outside is CLAMPED to it (the reply says so). A length that fits ONE clip of the render model renders as a single continuous pass; anything longer is STITCHED from acts filled to that model’s clip maximum with the remainder last (on a 15s-clip model, 40 → 15+15+10 and 17 → 13+4) — never time-compressed. The maximum is the model’s own: 15s on most, 30s on the longest-clip model, so a 30s ad can be one unbroken take rather than two acts. Omit when the user named no length; do NOT pass a guess, an omitted value keeps the recipe-aware default."
      }
    }
  }

  arguments 59 lines copy
• clone_video unknown never probed

  Remake a video you like FOR THIS BRAND from its link — a TikTok, Instagram Reel, Facebook video or reel, X post, YouTube Short or video, or a direct video file URL. Hermoso WATCHES it first (frames across the whole clip plus a transcript of the voiceover, on-screen text and cut map), then plans a storyboard that keeps its hook device, structure, jump cuts and pacing while swapping in THIS brand's product, cast, setting and words — never the original's words, face or brand. The new ad MATCHES THE ORIGINAL'S LENGTH (capped at 60s) unless durationSeconds is given. Renders nothing: pass the returned creative to render_ad to make the video. Costs the plan plus about 2 credits to read the link. The reply says exactly what was watched, and when a platform will not hand over the footage (YouTube sometimes refuses servers) it says the plan rests on the captions and thumbnail only. For a local file, upload_file it first and pass the URL.

  mcp-tool

  123456789101112131415161718192021222324252627282930313233343536373839404142

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "url"
    ],
    "properties": {
      "url": {
        "type": "string",
        "description": "the video to clone — a TikTok / Instagram Reel / Facebook / X / YouTube link, or a direct https video file URL"
      },
      "brand": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "object",
            "properties": {},
            "additionalProperties": {}
          }
        ],
        "description": "brand name or profile object; OMIT to use the workspace's saved brand (see get_brand)"
      },
      "changes": {
        "type": "string",
        "description": "what to change or keep from the original, in the user's words (e.g. \"same hook but in a gym\", \"keep the jump cut, older creator\")"
      },
      "product": {
        "type": "string",
        "description": "what the new ad sells, plus any angle or offer; omit to use the saved brand's product"
      },
      "language": {
        "type": "string",
        "description": "language for the new ad's script and copy — default English"
      },
      "durationSeconds": {
        "type": "number",
        "description": "override the length in seconds; omit to match the original"
      }
    }
  }

  arguments 42 lines copy
• generate_image unknown never probed

  Render a finished ad IMAGE and return its served URL. refImages (local paths or URLs) force product-accurate compositing (drops a real product into the scene). MULTI-BRAND CAUTION: useBrand hydration pulls the SAVED workspace brand — when working a brand that is NOT the saved one (a fresh draft_brand), pass that brand's own productImages/logo as refImages (and useBrand:false) or the output composites the WRONG brand's product. NOTE that the saved-brand hydration also decides the ENGINE: attaching product photos routes the render to the compositing model, so a `model` you named is only honoured when no references ride — pass raw:true (or useBrand:false) to render on exactly the model you asked for. model = a catalog id from hermoso_capabilities (omit for the default). PUTTING A REAL PRODUCT IN A REAL PERSON’S HANDS, or a garment on them, is a DIFFERENT KIND OF ROW and you must name it: the ids marked `needsRefs` with a `refsMax` in hermoso_capabilities take a person photo first and up to three product/garment photos after it, and they EDIT THE PHOTOGRAPH rather than compositing — THE PERSON IS RE-POSED to hold or wear the thing, so their stance and hands change while their face, clothing, setting and lighting are kept. That is not an object swap in a fixed frame; if you needed the rest of the photograph untouched, this is the wrong tool. Every finished render says which way it went. RAW MODEL ACCESS: raw:true dispatches your prompt to the model BYTE-IDENTICAL — no rewriting, no appended guidance, no negative prompt, no brand references attached on your behalf. Credits, the durable delivery of the finished asset and the per-model validation are unchanged. Fast (seconds). Spends credits.

  mcp-tool

  1234567891011121314151617181920212223242526272829303132333435363738394041424344

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "prompt"
    ],
    "properties": {
      "raw": {
        "type": "boolean",
        "description": "RAW MODEL ACCESS: run the caller’s prompt on the named model with no Hermoso adjustments at all — the prompt reaches the provider byte-identical (no hex-to-colour-name rewrite, no prepended fidelity preamble) and NO saved-brand product photos are attached, so the model you name is the model that renders. Use it to drive the raw catalog; leave it off for an on-brand ad. Billing, the durable Library landing and per-model validation are unchanged."
      },
      "mask": {
        "type": "string",
        "description": "MASKED EDIT — change ONE region of an image and keep the rest: a local path or URL of a mask image for refImages[0] (the image being edited). Either convention works and the reply says which it read: TRANSPARENT pixels = change, or, on a mask with no transparency, WHITE = change and black = keep. Any size; it is scaled to the image. The mask GUIDES the edit rather than stencilling it: the new content can blend a little past its edge. Runs on the model hermoso_capabilities marks `refs.mask` (gpt-image-2.5): leave `model` empty or name that one — any other named model is refused, free. Needs refImages; the result keeps the source image's own frame, so aspectRatio is not applied."
      },
      "model": {
        "type": "string",
        "description": "image model id from hermoso_capabilities. A model whose `refs.mode` is \"edit\" there (gpt-image-2.5) takes your refImages on ITS OWN editor, up to its `refs.max`, instead of the default compositor"
      },
      "prompt": {
        "type": "string",
        "description": "the full image prompt — subject, composition, lighting, and any on-image ad text. ON A POSE MODEL (product-in-hand / try-on) THIS IS EXTRA DIRECTION AND IT IS OPTIONAL — leave it out and the pose is built for you. If you do write one, DESCRIBE THE POSE (\"she holds the bottle upright in her right hand at chest height, label to camera\"); do NOT phrase it as a swap (\"replace the mug with the bottle\"), which is REFUSED for free, because the product then comes out the size of whatever it replaced — a 30ml bottle rendered mug-sized in testing."
      },
      "useBrand": {
        "type": "boolean",
        "description": "default true: with no refImages, the server hydrates the SAVED brand’s product/logo references so the output lands on-brand; pass false for a pure prompt-only render"
      },
      "imageSize": {
        "type": "string",
        "description": "pixel-size preset for models that support it: 1K/2K, and 4K on the models hermoso_capabilities lists with a 4K imageSize price (a 4K ask on any other model is refused, free) — omit for the default"
      },
      "refImages": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "local file paths or URLs of product/logo references to composite in. ON THE POSE MODELS — any row hermoso_capabilities marks `needsRefs` with a `refsMax`, such as putting your product in someone’s hands or a virtual try-on — THE ORDER IS THE CONTRACT AND IT IS NOT A COMPOSITE: refImages[0] is the PERSON photo, and the rest (up to `refsMax` minus one) are the product or garment photos. Reversed, you get the product wearing the person. A 4th product is dropped and the reply says so."
      },
      "aspectRatio": {
        "type": "string",
        "description": "e.g. '1:1', '9:16', '16:9'"
      }
    }
  }

  arguments 44 lines copy
• edit_image unknown never probed

  EDIT an existing image in place with a plain-language instruction and keep everything else: 'make the headline bigger', 'add our logo bottom right', 'swap the background for a kitchen', 'remove the person on the left', 'erase all the text'. Pass `image` (URL, Library item, upload_file URL or local path) and `instruction`. The same edit the web Studio's ✎ Edit runs: composition, aspect ratio, people and every untouched line of text stay as they are; the saved brand's real name and website are pinned so an added line never invents one, and the brand's real logo is attached when the instruction asks for the logo. Set removal:true when the edit STRIPS text, branding or an object, so nothing branded is put back. For a precise region, pass `mask` (see generate_image). One image edit's credits; returns the new image URL. For a new image from a prompt use generate_image; to rebuild a competitor's ad for your brand use clone_static.

  mcp-tool

  1234567891011121314151617181920212223242526

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "image",
      "instruction"
    ],
    "properties": {
      "mask": {
        "type": "string",
        "description": "optional mask image (URL or local path) marking the region to change: transparent = change, or white = change on an opaque mask"
      },
      "image": {
        "type": "string",
        "description": "the image to edit: URL, Library item URL, upload_file URL or local path"
      },
      "removal": {
        "type": "boolean",
        "description": "true when the edit REMOVES text, branding, a logo, a watermark, a person or an object, so the brand name and logo are not re-added"
      },
      "instruction": {
        "type": "string",
        "description": "the change to make, in plain words (pass the user’s own words for a removal or plain photo edit)"
      }
    }
  }

  arguments 26 lines copy
• headline_variants unknown never probed

  Turn ONE finished static ad into several copies that differ ONLY in the headline, for an A/B test: same picture, product, layout, colours and every other line. Pass `image`, and either `headlines` (your own, up to 10) or `count` (default 5, max 10) to have distinct angles written for you in the saved brand's voice (never inventing numbers, prices, ratings or claims the ad or brand does not state); `brief` steers what to test. The ad's text is read first (3 credits), then one image edit per headline; each output is proofread and flagged (textCheck) if the rendered words do not match, never silently re-rendered. The whole batch is priced before anything runs. Returns each headline, its angle and its image URL.

  mcp-tool

  123456789101112131415161718192021222324252627282930

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "image"
    ],
    "properties": {
      "brief": {
        "type": "string",
        "description": "what to test, e.g. \"price-led vs outcome-led\" or \"speak to busy parents\""
      },
      "count": {
        "type": "integer",
        "maximum": 10,
        "minimum": 1,
        "description": "how many headlines to write when `headlines` is omitted (default 5)"
      },
      "image": {
        "type": "string",
        "description": "the finished static ad: URL, Library item URL, upload_file URL or local path"
      },
      "headlines": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "your own headlines to test (up to 10); omit to have them written"
      }
    }
  }

  arguments 30 lines copy
• resize_ad unknown never probed

  Re-lay out ONE finished static ad for other placements: the same ad, product, copy (word for word), logo and style, recomposed natively for each canvas rather than cropped. Pass `image` and optionally `aspectRatios` from 1:1, 4:5, 9:16, 16:9, 3:4, 4:3 (default 1:1, 4:5 and 9:16; the ad's own ratio is skipped). Reads the ad's text first (3 credits) so every line survives, then one image edit per canvas. Priced before it runs. For VIDEO use reframe_video.

  mcp-tool

  12345678910111213141516171819202122232425262728

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "image"
    ],
    "properties": {
      "image": {
        "type": "string",
        "description": "the finished static ad: URL, Library item URL, upload_file URL or local path"
      },
      "aspectRatios": {
        "type": "array",
        "items": {
          "enum": [
            "1:1",
            "4:5",
            "9:16",
            "16:9",
            "3:4",
            "4:3"
          ],
          "type": "string"
        },
        "description": "target canvases (default 1:1, 4:5, 9:16)"
      }
    }
  }

  arguments 28 lines copy
• localize_ad unknown never probed

  Translate the on-image text of ONE finished static ad into other languages and keep everything else: same picture, layout, typeface, colours, logo and product. Pass `image` and `languages` (up to 5, e.g. ["Spanish", "German", "French (Canada)"]). The ad's text is read (3 credits), translated the way a native copywriter in each market would write it (brand and product names, URLs and prices kept as written), then one image edit per language; each output is proofread and flagged (textCheck) if the words do not match, never silently re-rendered. Priced before it runs. For a VIDEO use dub_video.

  mcp-tool

  1234567891011121314151617181920212223

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "image",
      "languages"
    ],
    "properties": {
      "image": {
        "type": "string",
        "description": "the finished static ad: URL, Library item URL, upload_file URL or local path"
      },
      "languages": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "maxItems": 5,
        "minItems": 1,
        "description": "target languages, by name"
      }
    }
  }

  arguments 23 lines copy
• make_thumbnail unknown never probed

  Render a click-driving YOUTUBE / Shorts / Instagram THUMBNAIL or video cover — the full production pipeline (concept framework → casting → scene → render → surgical tweaks → text), not a bare image prompt. Use this for any "thumbnail", "video cover", "video preview" or MrBeast-style packaging ask INSTEAD of generate_image. About 9 credits per variant; the headline overlay is free. CONCEPT — every thumbnail must open an INFORMATION GAP (the image raises a question the title answers) while staying truthful to the video. Brainstorm ≥5 concepts across the 16 frameworks before you pick, and feel free to combine two. Frameworks (pass as `framework`): before_after · social_ui · three_step · screenshot · posed_portrait (the default) · posed_action · specific_day · graphical · landscape · map_aerial · product · adding_text · repetition · size_difference · news_clip · amplified_reality. Call hermoso_capabilities for each one's full 'realize it with' note plus the emotion, overlay-style, font and rim-colour catalogs. THREE GATES, all BEFORE you render: 1. WHO IS IN FRAME — never assume and never silently substitute a stranger. If the framework puts a person in frame and no face photo is attached, the tool refuses (nothing rendered, nothing charged) and tells you to ask the user once: themselves (send a face photo → the identity gets locked), a generated person (`castGenericPerson:true`), or a people-free framework. 2. TEXT — the default is a CLEAN render with the headline TYPESET OVER THE TOP afterwards (free, always legible, correctly spelled). Just pass `headline`. Only set `bakeText:true` if the user explicitly asks for the words painted INTO the image — verified live, that renders the asked-for words correctly but leaks garbled invented text across the rest of the frame. Never infer text intent from the topic or the framework. 3. HOW MANY — ask once whether they want one thumbnail or a SET (offer 4: the same concept at different emotions and/or camera takes). Default is 1; `variants` caps at 16. IDENTITY LOCK is automatic for every attached face photo. `emotion` is the single biggest CTR lever on a face: shock · hype · fear · confusion · determination · smug · charisma · disgust · awe · rage · laugh (or your own phrase). Finished thumbnail needs a fix? Re-call with `tweak` + `sourceImage` for a surgical, pixel-faithful edit (emotion / background / background_color / rim_light) instead of re-rendering — tweaks chain. ALWAYS check the returned postRenderCheck against the image before you present it. PROMPT LANGUAGE — write every DESCRIPTIVE field in ENGLISH (`sceneBrief`, `keyElements`, `location`, `composition`, `background`, `topic`, each person's `describe`, and every `reference` field), translating the user's wording where needed: the image models are trained on English and a non-English scene description renders noticeably worse. Text that gets BAKED OR TYPESET stays verbatim in the user's own language — `headline`, `headlineLines` and `bakedUiText` are never translated.

  mcp-tool

  123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "font": {
        "type": "string",
        "description": "headline font (default Anton). Alternatives incl. Bebas Neue, Oswald, Archivo Black, Montserrat, Inter, Playfair Display"
      },
      "logo": {
        "type": "string",
        "description": "a brand logo URL or path to place into the composition"
      },
      "split": {
        "type": "object",
        "required": [
          "mode"
        ],
        "properties": {
          "mode": {
            "enum": [
              "plain",
              "before_after",
              "versus",
              "custom"
            ],
            "type": "string"
          },
          "panels": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "description": "split/panel LAYOUT — only when the user asks for one (\"split\", \"before/after\", \"versus screen\"). \"X vs Y\" as a SCENE stays one unified frame",
        "additionalProperties": {}
      },
      "takes": {
        "type": "number",
        "description": "camera takes per emotion, 1–4: designed framing / low-angle hero / extreme close-up / wide dutch tilt"
      },
      "topic": {
        "type": "string",
        "description": "the video's topic — used to pick the hero object when you don't name keyElements"
      },
      "tweak": {
        "type": "object",
        "required": [
          "kind",
          "value"
        ],
        "properties": {
          "kind": {
            "enum": [
              "emotion",
              "background",
              "background_color",
              "rim_light"
            ],
            "type": "string"
          },
          "value": {
            "type": "string"
          }
        },
        "description": "surgical pixel-faithful edit of a FINISHED thumbnail — needs sourceImage"
      },
      "logo3d": {
        "type": "boolean",
        "description": "first turn the flat logo into a volumetric 3D render (one extra billed image), then composite that"
      },
      "people": {
        "type": "array",
        "items": {
          "type": "object",
          "required": [
            "describe"
          ],
          "properties": {
            "describe": {
              "type": "string"
            }
          },
          "additionalProperties": {}
        },
        "description": "people described in prose instead of by photo (each still gets the chosen expression)"
      },
      "emotion": {
        "type": "string",
        "description": "the expression on the face (default 'shock') — a preset id or your own phrase"
      },
      "bakeText": {
        "type": "boolean",
        "description": "default false. true paints the headline INTO the generation — only on an explicit user ask; it leaks garbled text elsewhere in the frame"
      },
      "emotions": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "render one variant per emotion (variants = emotions × takes, max 16)"
      },
      "headline": {
        "type": "string",
        "description": "2–4 word headline. Typeset OVER the finished render by default (free, always legible); newlines split it into stacked lines"
      },
      "location": {
        "type": "string",
        "description": "place, time of day, weather, atmosphere"
      },
      "rimColor": {
        "type": "string",
        "description": "colored back+hair light — ONLY when the user names one: 'ice-blue' / 'neon-magenta' / 'toxic-lime' / 'amber-gold' / 'pure-white'"
      },
      "variants": {
        "type": "number",
        "description": "how many thumbnails to render (default 1, max 16). Each is its own billed render — offer a set of 4 rather than assuming"
      },
      "framework": {
        "type": "string",
        "description": "concept framework id (default 'posed_portrait'); see the list in this description / hermoso_capabilities"
      },
      "reference": {
        "type": "object",
        "properties": {},
        "description": "fields YOU extracted by eye from a reference thumbnail. Extract ALL of: brief (one dense sentence on the concept), subject (pose/action generically, NEVER a specific identity), elements, location, composition, background, split (boolean), split_count, person_count (0-3), emotion (one of the 11 presets or 'other'), emotion_detail (one vivid sentence covering eyes, brows, mouth, head angle). emotion + emotion_detail carry the reference's actual facial performance, which is the single biggest CTR lever on a face; split/split_count reproduce its panel structure. The reference image itself is never sent to the model",
        "additionalProperties": {}
      },
      "background": {
        "type": "string",
        "description": "override the default bold saturated colour-field background"
      },
      "faceImages": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "up to 3 face photos (URLs or local paths) — each becomes a locked CHARACTER identity, in order"
      },
      "sceneBrief": {
        "type": "string",
        "description": "what the thumbnail depicts — the concept in one dense sentence, rendered exactly"
      },
      "aspectRatio": {
        "type": "string",
        "description": "'16:9' (YouTube, default) / '9:16' (Shorts) / '4:5' (Instagram) / '4:3' / '1:1'"
      },
      "bakedUiText": {
        "type": "string",
        "description": "short label for a text-carrying framework (a chat bubble, a DAY N badge, a news lower-third, a map callout) — needs frameworkRequested:true"
      },
      "composition": {
        "type": "string",
        "description": "override the default large-foreground-subject composition"
      },
      "keyElements": {
        "type": "string",
        "description": "signature props / effects that make it pop — oversized, flying toward camera"
      },
      "sourceImage": {
        "type": "string",
        "description": "the finished thumbnail URL a `tweak` edits; tweaks chain, so feed each accepted output into the next"
      },
      "overlayStyle": {
        "type": "string",
        "description": "headline style: 'beast' (default, white + heavy black stroke) / 'fire' / 'neon-lime' / 'clean-glass' / 'marker'"
      },
      "forceGenerate": {
        "type": "boolean",
        "description": "render the 'screenshot' framework anyway (it is normally a real video frame, not a generation)"
      },
      "headlineLines": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "explicit headline lines (up to 3) — overrides splitting `headline` on newlines"
      },
      "headlinePlace": {
        "enum": [
          "bottom",
          "top",
          "center"
        ],
        "type": "string",
        "description": "where the headline sits — never over the face (default 'bottom')"
      },
      "restrainedGrade": {
        "type": "boolean",
        "description": "true for a calm / premium / muted look instead of the default punchy poster grade"
      },
      "castGenericPerson": {
        "type": "boolean",
        "description": "pass true only after the user has explicitly chosen a generated stranger over their own face"
      },
      "frameworkRequested": {
        "type": "boolean",
        "description": "true ONLY when the USER named this framework — it is what authorizes a text-carrying framework (social_ui / news_clip / specific_day / map_aerial) to bake its short UI label"
      }
    }
  }

  arguments 201 lines copy
• generate_voice unknown never probed

  RAW text-to-speech from the voice-model catalog: speak a script in a chosen voice and return the served MP3 URL. For a standalone voiceover / narration clip — NOT for adding audio to a video (render_ad and generate_video voice their own spots; change_voice re-voices a finished clip). engine picks the voice model (default 'seed-audio'; also 'eleven-v3', 'minimax-speech', 'kokoro'); voice is a preset name from that engine (see hermoso_capabilities → voice engines) — a name that engine does not have is REFUSED for free with its real list, and a few engines generate their own voice and take no preset at all (the reply says which voice actually spoke). Paid (a couple of credits by length; ≤900 characters).

  mcp-tool

  123456789101112131415161718192021

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "text"
    ],
    "properties": {
      "text": {
        "type": "string",
        "description": "the script to speak (≤900 characters)"
      },
      "voice": {
        "type": "string",
        "description": "a voice preset from the chosen engine (e.g. 'Aria'/'George' on eleven-v3, 'stokie_en' on seed-audio) — omit for the engine default"
      },
      "engine": {
        "type": "string",
        "description": "voice-engine id: 'seed-audio' (default), 'eleven-v3', 'minimax-speech', or 'kokoro' — listed in hermoso_capabilities"
      }
    }
  }

  arguments 21 lines copy
• generate_text unknown never probed

  Text generation against the writing-model catalog (Claude, Gemini, GPT, Llama, DeepSeek…) — ad copy, hooks, scripts, rewrites, brainstorms. Prompt-only, no ad assembly (for a finished on-brand creative use plan_ad → render_ad). BY DEFAULT the model answers as a marketing copywriter (a short house system prompt is applied, which is what you want for ad copy); pass raw:true for a plain, unstyled answer from the model itself with NO system prompt at all. model = a writing-model id from hermoso_capabilities (omit for the default Claude orchestrator). Paid (a credit or two by length).

  mcp-tool

  123456789101112131415161718192021

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "prompt"
    ],
    "properties": {
      "raw": {
        "type": "boolean",
        "description": "RAW MODEL ACCESS: send the prompt with NO Hermoso system prompt — the model answers as itself rather than as an ad copywriter. Use it whenever the ask is not marketing copy (analysis, code, extraction, a plain question). Default false: the copywriter framing is applied."
      },
      "model": {
        "type": "string",
        "description": "a writing-model id from hermoso_capabilities (a Claude / Gemini / GPT / Llama / DeepSeek id) — omit for the default"
      },
      "prompt": {
        "type": "string",
        "description": "the writing task / question"
      }
    }
  }

  arguments 21 lines copy
• render_ad unknown never probed

  RECOMMENDED for finished video ADS: render a plan_ad concept through the SAME quality pipeline as the Hermoso web Studio — timed shot list, exact/clean speech (no garbled words), text composited in post (never model-painted), an optional brand end card (only when the user asks), licensed music bed, real product references. Pass plan_ad’s full structured output as `creative`. Honors the plan’s render_plan structure/duration: a storyboard that FITS ONE CLIP OF THE RENDER MODEL renders as a single continuous pass; anything longer automatically renders as STITCHED ACTS (the fewest balanced clips, each at most one model clip) — never time-compressed into one clip. That threshold is the render model’s own maximum, not a fixed number: most models cap a clip at 15s and the longest-clip one goes to 30s, so use dryRun:true to see the act split this plan will actually get, for free, before spending. CAST A SAVED CREATOR with `creator` so the SAME person stars in this ad as in the last one (list_creators is the roster) — otherwise every render invents a new face. Renders take 1–3 min; keep polling get_job if it returns still-rendering. Spends credits.

  mcp-tool

  123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "creative"
    ],
    "properties": {
      "model": {
        "type": "string",
        "description": "video model id from hermoso_capabilities (default: the plan’s pick). Naming one is a DELIBERATE pick — the server asks before ever swapping it (no silent fallback)"
      },
      "music": {
        "type": "boolean",
        "description": "licensed music bed on/off (default on)"
      },
      "dryRun": {
        "type": "boolean",
        "description": "return the routing decision (single pass vs stitched acts, resolved model + act lengths) WITHOUT submitting a render — free, nothing charged"
      },
      "lockup": {
        "type": "boolean",
        "description": "brand wordmark + tagline composited over the closing seconds. DEFAULT FALSE — set true ONLY when the user asks for branding on the close"
      },
      "creator": {
        "type": "string",
        "description": "CAST A SAVED CREATOR in this ad — their id from list_creators, or the name you know them by (“Sarah”). Their saved portrait becomes the on-camera identity for the whole spot, so the same face carries across every act and across every ad you render for this brand — and because we already have their picture, the character portrait this pipeline would otherwise generate is skipped, so casting somebody costs LESS than not casting them. Omit to let the ad cast a fresh person. Refused for free, with nothing rendered, if the name matches nobody or more than one creator, if the plan has nobody on camera, or if they are a REAL person with no likeness consent on file."
      },
      "endCard": {
        "type": "boolean",
        "description": "append the branded end card. DEFAULT FALSE on every recipe — set true ONLY when the user asks for an end card (a clone of a video that had none should not grow one)"
      },
      "captions": {
        "type": "boolean",
        "description": "burn the plan's per-scene on-screen words as caption pills. DEFAULT FALSE on every recipe — set true ONLY when the user asks for on-screen text or captions; no recipe turns them on by itself"
      },
      "creative": {
        "type": "object",
        "properties": {},
        "description": "the FULL structured output of plan_ad (must contain video_storyboard)",
        "additionalProperties": {}
      },
      "ttsVoice": {
        "type": "string",
        "description": "voiceover voice name (e.g. Rachel / George) when the plan voices over"
      },
      "textStyle": {
        "anyOf": [
          {
            "enum": [
              "pill",
              "editorial",
              "bold",
              "minimal",
              "handwritten",
              "boxed"
            ],
            "type": "string"
          },
          {
            "type": "object",
            "properties": {
              "font": {
                "enum": [
                  "sans",
                  "serif",
                  "elegant",
                  "condensed",
                  "hand"
                ],
                "type": "string"
              },
              "size": {
                "anyOf": [
                  {
                    "enum": [
                      "s",
                      "m",
                      "l",
                      "xl"
                    ],
                    "type": "string"
                  },
                  {
                    "type": "number"
                  }
                ]
              },
              "tilt": {
                "type": "number",
                "description": "degrees, ±12"
              },
              "color": {
                "type": "string",
                "description": "#hex"
              },
              "italic": {
                "type": "boolean"
              },
              "preset": {
                "enum": [
                  "pill",
                  "editorial",
                  "bold",
                  "minimal",
                  "handwritten",
                  "boxed"
                ],
                "type": "string"
              },
              "shadow": {
                "type": "boolean"
              },
              "weight": {
                "type": "number"
              },
              "outline": {
                "type": "boolean"
              },
              "subFont": {
                "enum": [
                  "sans",
                  "serif",
                  "elegant",
                  "condensed",
                  "hand"
                ],
                "type": "string"
              },
              "position": {
                "enum": [
                  "top",
                  "center",
                  "lower",
                  "bottom"
                ],
                "type": "string"
              },
              "textCase": {
                "enum": [
                  "as-is",
                  "upper",
                  "lower",
                  "title"
                ],
                "type": "string"
              },
              "cardColor": {
                "type": "string",
                "description": "#hex end card background"
              },
              "subItalic": {
                "type": "boolean"
              },
              "background": {
                "type": "string",
                "description": "\"none\", \"pill\", or a #hex box"
              }
            }
          }
        ],
        "description": "THE LOOK of captions and the end card — only meaningful with captions:true or endCard:true, and only when the user described a look. Presets: editorial (a large elegant serif title mid-frame with a small italic line under it, no box), bold (tall condensed caps with a black outline), minimal (small lowercase near the bottom), handwritten (tilted marker), boxed (dark words on a white box), pill (the plain default). Pass a preset name, or an object with a preset plus overrides. A caption written \"TITLE · small line\" puts the part after the middle dot on a second line. An invalid field is refused by name before anything renders."
      },
      "resolution": {
        "enum": [
          "480p",
          "720p",
          "1080p",
          "4k"
        ],
        "type": "string",
        "description": "'1080p' default (what we ship and bill for); '480p'/'720p' = cheaper draft passes, '4k' = premium final delivery (more credits). NOT EVERY MODEL OFFERS EVERY TIER — this enum is what the tool accepts, and each model's OWN `resolutions` list in hermoso_capabilities is what it can actually render (the longest-clip 30s model, for one, tops out at 720p). Ask for a tier the chosen model does not list and it is rendered at that model's best available tier instead, with nothing in the reply saying so — so check `resolutions` before promising anyone 1080p or 4k."
      },
      "aspectRatio": {
        "type": "string",
        "description": "output aspect ratio, e.g. 9:16 (default) / 1:1 / 16:9"
      },
      "durationSeconds": {
        "type": "number",
        "description": "total ad length in seconds (supported range 4–180; outside that it is clamped). Omit to honor the plan’s own duration — that is almost always right. This only RE-TIMES an already-authored board (its scenes are scaled to fit), it does NOT re-write it, so to change the length of the ad the user asked for, re-run plan_ad with durationSeconds instead. A length that fits ONE clip of the render model renders as one continuous pass; longer is stitched from acts filled to that model’s clip maximum with the remainder last — the maximum is 15s on most models and 30s on the longest-clip one, so use dryRun:true to see the exact act split for free before spending."
      },
      "allowGenericProduct": {
        "type": "boolean",
        "description": "proceed even though this brand has NO product photo on file and the ad features a product — the packaging will be INVENTED. Only pass true after telling the user that and hearing they are fine with a generic stand-in"
      }
    }
  }

  arguments 186 lines copy
• make_template_ad unknown never probed

  Render a NATIVE-STYLE TEMPLATE ad from pure HTML — no AI video/image model in the loop, renders in ~30 seconds for a couple of credits. Perfect for native-feel social ads at volume. YOU author the content (short, casual, believable — never marketing-speak). Templates (pass as config.template): 'imessage-chat' (VIDEO ~15s: a real-looking iMessage thread where a friend reveals the product as a rich-link card; config: { thread: { contactName, messages: [{from:'them'|'me', text?, product?:{image,title,domain}}] }, theme?:'dark'|'light', endCard:{headline,cta,domain,logo?,color} } — 4-6 short lowercase bubbles, product card mid-thread from 'me', 1-2 excited replies after); 'chatgpt-chat' (VIDEO: a ChatGPT answer streams the punchline; config: { question, answer (may **bold** the brand), productImage?, endCard }); 'apple-notes' (VIDEO: an iPhone note types itself out; config: { title, lines: string[], theme?, endCard }); 'value-prop' (VIDEO ~17s kinetic typography: config: { hook (≤40 chars), claims: string[] (3-5 COMPLETE phrases, ≤6 words / ≤34 chars each — a finished thought, NEVER a clipped clause like 'Looks good on any'), productImages: string[] (2-3 DISTINCT photos — one rotates per card), palette: string[], endCard }); 'static-mockup' (IMAGE: config: { style:'imessage'|'notes'|'card', size?:{w,h}, ...style fields }); 'airdrop-carousel' (VIDEO ~10s: an iOS AirDrop share card springs up and cycles 3-16 REAL product photos to a full-lineup payoff; config: { brandName, products: [{image, title?}], contactLine?, endCard }); 'app-ui-tour' (VIDEO ~12-16s for APP brands: floating-iPhone mockup walks through REAL app screenshots with kinetic captions; config: { hook?, appName, iconImage?, beats: [{screenImage, caption}] (2-6), palette?, fontStack?, endCard }); 'imessage-cascade' (VIDEO ~12s: iOS notification banners spring in and stack over a blurred backdrop; config: { notifications: [{sender, text}] (4-8), backgroundImage?, endCard }); 'photo-grid' (VIDEO ~8s: collage assembles real photos one at a time; config: { title?, photos: [{image, label?}] (4-9), palette?, fontStack?, endCard }); 'vignette' (VIDEO ~12s: cinematic Ken-Burns hero film; config: { hook, lines: [2-4 ≤40ch], heroImage, palette?, fontStack?, endCard }); 'kinetic-type' (VIDEO ~9-15s typographic motion design with NO VOICEOVER — it is NOT a silent asset: it always carries its own synthesised SFX (whoosh/tick/chime) and, once a curated track is on file, the family's loudest music bed at -16 LUFS; config.music:'off' silences the bed but never the SFX: 3-6 short phrases each land word by word on a full-bleed brand card (product beats caption the phrase over the photo instead), the longest word picked out in the brand accent, and a skewed accent slab wipes every cut; supply productImages and every OTHER beat becomes a full-bleed product shot with its phrase captioned over it — with none it renders as pure typography, so it needs NO photos; config: { phrases: string[] (3-6, ≤34 chars each — punchy, declarative, ONE idea per phrase, a finished thought never a clipped clause), productImages?: string[] (up to 4 DISTINCT photos), palette?: string[], fontStack?, endCard }); 'myth-vs-fact' (VIDEO ~15-26s VO-FIRST kinetic explainer with a real VOICEOVER — the family's ONE paid-audio format: a calm-authority read busts 2-4 myths, each MYTH line slamming in with a red per-line strike then the counter FACT line landing bold+affirmative, word-level KARAOKE lighting each word as the VO speaks it; config: { pairs: [{ myth (≤50ch, the common wrong belief), fact (≤60ch, the corrective truth — wrap its payoff phrase in [brackets] to accent it) }] (2-4), palette?, fontStack?, endCard }. Real product truths only — NEVER invent stats. Costs the flat template credits PLUS a small voiceover charge); 'carousel' (MULTI-IMAGE: 5-10 branded 1080×1080 PNG slides for Meta/LinkedIn/IG carousels — returns an images[] array, one PNG per slide; config: { cover: { hook?, title }, slides: [{ headline (≤8 words), support? (≤16 words), stat?: { value, label } }] (3-8; a stat slide is a REAL user-supplied number like '94%' or '40k+' + a label, never invented), cta: { headline, cta?, domain? }, productImage?, logo?, palette?, fontStack?, endCardColor? }). Every VIDEO format except myth-vs-fact (VO-first, deliberately dry) also gets a mood-matched MUSIC BED when a curated track is on file (the library ships empty — no track means no bed, never a paid generation) under its own SFX, from the curated library — free, no model, no extra credits; set config.music:'off' for a silent cut or a mood name (upbeat/calm/warm/epic/tense/playful/elegant/hype/chill/dramatic) to re-mood it. Image URLs may be any public URL — the server localizes them. Spends a couple of credits.

  mcp-tool

  123456789101112131415

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "config"
    ],
    "properties": {
      "config": {
        "type": "object",
        "properties": {},
        "description": "the template config — MUST include config.template (one of the template ids above) plus that template's fields",
        "additionalProperties": {}
      }
    }
  }

  arguments 15 lines copy
• finish_video unknown never probed

  Post-process an EXISTING rendered video (its served mp4 URL) with the proven direct-response 'reviewer' finish and/or a film-grain pass — no AI model, ~30s, a couple of credits. pills=true composites a header pill (e.g. '10/10 would buy again'), a brand-accent sub-pill, and 3-4 green-check proof pills cascading in on the beat (YOU author the copy: header ≤40 chars, sub ≤34, each point ≤44 — concrete real benefits, never fabricated stats). grain=true applies a subtle camera-grain finish that makes photoreal AI renders look phone-shot ('less AI') — works alone or with pills. Returns a NEW video; the original is untouched.

  mcp-tool

  12345678910111213141516171819202122232425262728293031323334353637383940

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "videoUrl"
    ],
    "properties": {
      "sub": {
        "type": "string",
        "description": "accent sub-pill copy, ≤34 chars (usually the product/brand)"
      },
      "grain": {
        "type": "boolean",
        "description": "default false — anti-AI film-grain finish"
      },
      "pills": {
        "type": "boolean",
        "description": "default true — set false for a grain-only pass"
      },
      "accent": {
        "type": "string",
        "description": "brand accent hex for the sub-pill"
      },
      "header": {
        "type": "string",
        "description": "header pill copy, ≤40 chars (required when pills is on)"
      },
      "points": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "3-4 proof points, ≤44 chars each"
      },
      "videoUrl": {
        "type": "string",
        "description": "the served URL of the video to finish (from a previous render/job)"
      }
    }
  }

  arguments 40 lines copy
• post_edit unknown never probed

  MECHANICAL post-production on an EXISTING rendered video (its served mp4 URL) — an ordered plan of whitelisted primitives executed by ffmpeg (+ Chrome for typeset cards) in seconds for ~2 credits flat, NO AI model, the original untouched (returns a NEW video). The lane for: append a branded end card ('add an end card with our logo and website' — ADDS its seconds, never re-renders), trim, speed (0.5-2x), mute (whole or a window), audio_gain (-20..+6 dB), fade_out, corner logo watermark, anti-AI film grain. Up to 6 ops per plan, applied in order. Brand assets (name/domain/logo/accent) load from the workspace brand automatically; override per-call if needed. NEVER use generate_video/render_ad for these mechanical asks.

  mcp-tool

  123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "videoUrl",
      "ops"
    ],
    "properties": {
      "ops": {
        "type": "array",
        "items": {
          "type": "object",
          "required": [
            "op"
          ],
          "properties": {
            "db": {
              "type": "number",
              "description": "audio_gain -20..+6 dB"
            },
            "op": {
              "enum": [
                "trim",
                "speed",
                "mute",
                "audio_gain",
                "fade_out",
                "append_card",
                "watermark",
                "grain"
              ],
              "type": "string"
            },
            "end": {
              "type": "number",
              "description": "trim/mute window end (s)"
            },
            "sub": {
              "type": "string",
              "description": "append_card: the pill line (defaults to the brand website)"
            },
            "start": {
              "type": "number",
              "description": "trim/mute window start (s)"
            },
            "corner": {
              "enum": [
                "tl",
                "tr",
                "bl",
                "br"
              ],
              "type": "string",
              "description": "watermark corner (default br)"
            },
            "factor": {
              "type": "number",
              "description": "speed 0.5-2"
            },
            "seconds": {
              "type": "number",
              "description": "fade_out 0.3-3s / append_card 2-5s"
            },
            "tagline": {
              "type": "string",
              "description": "append_card: smaller line under the headline"
            },
            "headline": {
              "type": "string",
              "description": "append_card: big line (defaults to the brand name)"
            },
            "card_html": {
              "type": "string",
              "description": "append_card: your OWN full-frame card design as inline-styled HTML ({{logo}} inserts the real brand logo) — use when the standard layout cannot honor the request"
            },
            "intensity": {
              "enum": [
                "default",
                "strong"
              ],
              "type": "string",
              "description": "grain look"
            },
            "background": {
              "type": "string",
              "description": "append_card: card background — hex or a color name ('red', 'navy'…); the user's stated color always wins over the brand palette"
            }
          }
        },
        "description": "the ordered edit plan (max 6 ops)"
      },
      "accent": {
        "type": "string",
        "description": "override the brand accent hex"
      },
      "domain": {
        "type": "string",
        "description": "override the brand website"
      },
      "videoUrl": {
        "type": "string",
        "description": "the served URL of the video to edit"
      },
      "brandName": {
        "type": "string",
        "description": "override the workspace brand name"
      }
    }
  }

  arguments 109 lines copy
• fix_beat unknown never probed

  Surgically re-render ONE time window (1.5-8s) of an existing rendered video and splice it back on the VIDEO TRACK ONLY — the rest of the video and ALL audio stay byte-identical. Use when one beat/shot is broken ('the shot at 8 seconds glitches') and a full re-render would waste the parts that worked; bills only the replacement clip's seconds (~1/3 of a full render). Do NOT pick a window covering spoken dialogue (a video-only splice under speech breaks lip-sync) — pass speechWindows to enforce this.

  mcp-tool

  123456789101112131415161718192021222324252627282930313233343536373839404142

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "videoUrl",
      "startSeconds",
      "endSeconds",
      "prompt"
    ],
    "properties": {
      "prompt": {
        "type": "string",
        "description": "what the replacement footage should show — describe the shot, matching the master's style"
      },
      "refImage": {
        "type": "string",
        "description": "optional product/style anchor image URL"
      },
      "videoUrl": {
        "type": "string",
        "description": "the served URL of the master video to fix"
      },
      "endSeconds": {
        "type": "number",
        "description": "window end in seconds (window 1.5-8s)"
      },
      "startSeconds": {
        "type": "number",
        "description": "window start in seconds"
      },
      "speechWindows": {
        "type": "array",
        "items": {
          "type": "array",
          "items": {
            "type": "number"
          }
        },
        "description": "[[start,end],...] windows with spoken lines — the fix window must not overlap these"
      }
    }
  }

  arguments 42 lines copy
• clip_video unknown never probed

  Cut ONE long video into several RANKED, ready-to-post short clips (podcast, webinar, interview, conference talk, long ad cut → Reels/Shorts/TikTok). Transcribes the source with timestamps, picks the strongest SELF-CONTAINED moments, then cuts + reframes each with ffmpeg — no video model renders anything, which is why it's fast and cheap. THE VERTICAL REFRAME IS SUBJECT-AWARE: a few stills per clip go to ONE cheap vision call, which decides a SINGLE crop offset that is held for that clip's whole length — so a speaker sitting camera-left is not cropped out of their own clip, while the framing still never drifts INSIDE a clip. It costs one small vision call per clip, billed as its own event. When nothing is being discarded, or no single subject can be located, the crop stays dead centre — read `reframedToSubject` and each clip's `reframeWhy` back off the result rather than assuming either way. ACCEPTS: (a) a YouTube link (or Vimeo / Loom / Dailymotion / Streamable / Rumble / Wistia / Twitch / TED) — the server pulls the video down itself; (b) a direct https .mp4/.mov/.webm; (c) a Hermoso /generated/ URL (upload_file turns a local file into one). NOT supported: TikTok / Instagram / Facebook links, and anything age-restricted, private, members-only, geo-blocked or still LIVE — those fail fast with the real reason and are fully refunded, so ask for a direct file or an upload rather than retrying. Source must be at least ~15s and under ~600MB; only the first ~40 minutes is analysed (the result reports truncated:true when it hits that). Cost: a ~7-credit hold, settled to the exact transcription + encode cost, plus the clip-selection model's tokens billed as their own small event. RETURNS clips[] — each with its OWN served mp4 URL, title, hook, ready-to-post caption, 0-100 score and source timecode — not a single video. SUBTITLES ARE BURNED IN BY DEFAULT — slim white CAPS, thin black outline, bottom safe band, no box and no plate — because short-form is watched on mute; pass captions:false for clean footage. TIMING IS APPROXIMATE, NOT WORD-LEVEL: each cue is anchored to the transcript's own per-sentence timestamp and split inside a sentence by character count, so it tracks the speech closely but is not frame-accurate sync — never promise that. Read captionsBurned back off the result: it counts the clips that actually carry a burned track, and captionNote says why any are bare.

  mcp-tool

  12345678910111213141516171819202122232425262728293031

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "video"
    ],
    "properties": {
      "count": {
        "type": "number",
        "description": "how many clips to cut, 1-8 (default 4)"
      },
      "video": {
        "type": "string",
        "description": "the long video to clip — a YouTube/Vimeo/Loom/Dailymotion/Streamable/Rumble/Wistia/Twitch/TED watch URL, a direct https .mp4/.mov/.webm, or a Hermoso /generated/ URL"
      },
      "captions": {
        "type": "boolean",
        "description": "burn subtitles into every clip. DEFAULT TRUE — a clip cut from a podcast or a talk is watched on mute, and the words are the product. Set false for clean footage. A clip whose window carries no readable speech is delivered bare rather than captioned with a guess, and the result says which."
      },
      "aspectRatio": {
        "enum": [
          "9:16",
          "1:1",
          "16:9",
          "keep"
        ],
        "type": "string",
        "description": "clip shape — '9:16' (default) vertical for Reels/Shorts/TikTok; 'keep' leaves the source framing untouched"
      }
    }
  }

  arguments 31 lines copy
• add_subtitles unknown never probed

  Burn subtitles into ANY existing video and get the .srt too. It transcribes the speech and burns short readable lines onto the whole video; nothing is cut or re-rendered. Set textStyle only when the user describes a look; with none, white sentence-case text with a thin outline sits in the bottom safe band. Timing is approximate (per spoken sentence), not word-level sync. burn:false returns only the .srt. Takes a /generated/ URL, a direct .mp4/.mov/.webm, or a YouTube/Vimeo/Loom-style link; not TikTok, Instagram or Facebook. No speech is refused and refunded. Runs in the background and lands in the Library.

  mcp-tool

  123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "video"
    ],
    "properties": {
      "burn": {
        "type": "boolean",
        "description": "false = only the .srt"
      },
      "video": {
        "type": "string",
        "description": "the video to subtitle"
      },
      "textStyle": {
        "anyOf": [
          {
            "enum": [
              "pill",
              "editorial",
              "bold",
              "minimal",
              "handwritten",
              "boxed"
            ],
            "type": "string"
          },
          {
            "type": "object",
            "properties": {
              "font": {
                "enum": [
                  "sans",
                  "serif",
                  "elegant",
                  "condensed",
                  "hand"
                ],
                "type": "string"
              },
              "size": {
                "anyOf": [
                  {
                    "enum": [
                      "s",
                      "m",
                      "l",
                      "xl"
                    ],
                    "type": "string"
                  },
                  {
                    "type": "number"
                  }
                ]
              },
              "tilt": {
                "type": "number",
                "description": "degrees, ±12"
              },
              "color": {
                "type": "string",
                "description": "#hex"
              },
              "italic": {
                "type": "boolean"
              },
              "preset": {
                "enum": [
                  "pill",
                  "editorial",
                  "bold",
                  "minimal",
                  "handwritten",
                  "boxed"
                ],
                "type": "string"
              },
              "shadow": {
                "type": "boolean"
              },
              "weight": {
                "type": "number"
              },
              "outline": {
                "type": "boolean"
              },
              "position": {
                "enum": [
                  "top",
                  "center",
                  "lower",
                  "bottom"
                ],
                "type": "string"
              },
              "textCase": {
                "enum": [
                  "as-is",
                  "upper",
                  "lower",
                  "title"
                ],
                "type": "string"
              },
              "background": {
                "type": "string",
                "description": "none | pill | #hex box"
              }
            }
          }
        ],
        "description": "the look: a preset or overrides; omit for the default"
      }
    }
  }

  arguments 117 lines copy
• make_explainer unknown never probed

  Turn a TOPIC into a finished narrated explainer video. Writes a sectioned script, paints a BURST of pictures per section (about one every 1.5s — most of them one-detail edits of the frame before, so it reads as movement rather than a slideshow), narrates each section with TTS, holds each picture PERFECTLY STILL for its own slice of the narration (the motion is the CUT RATE — a slow move on a still shimmers), then composites the end card (and any on-screen text you asked for) with the Chrome+ffmpeg engine the ads use (text is never model-painted, so it never garbles). BURNED ON-SCREEN TEXT IS OFF BY DEFAULT — the narration carries the point and the pictures carry the story, so the film ships clean unless the user asks otherwise; `captions:true` adds held key points and `subtitles:true` adds narration-timed CAPS (see both). It is an image film WITH motion, not N video-model renders — that's what keeps it affordable. `style` picks the visual family: the default 'cinematic' is photoreal editorial; every other id is a STYLED, strictly non-photoreal look (illustrated / collage / clay / pixel …) that first renders ONE style-key image and then locks every scene to it, so the whole film holds one look. Cost at the default frame density: a ~130-credit hold for a 60s explainer on the default style, ~100 styled; `frameDensity:'lean'` roughly halves it and `'minimal'` (one picture per section) is ~30. All settle to the exact per-frame image + narration spend (a longer target = more sections = more). Takes SEVERAL minutes — one image render per frame; independent frames are painted concurrently, so it is far faster than the frame count suggests. Needs the writing model and a narration voice engine connected. NOT the tool for a short product ad — use render_ad or generate_video for those, and make_template_ad for the deterministic native formats.

  mcp-tool

  123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "topic"
    ],
    "properties": {
      "music": {
        "type": "string",
        "description": "music bed under the narration, measured to sit about 14 dB under the voice and sidechain-ducked beneath it. Omit and the KIDS and FAIRYTALE channels get their recommended bed COMPOSED for this film — those two are the only channels a bed is due on unasked, and it costs a small flat fee; every other channel ships dry. 'off' forces silence. 'library' takes a free curated track only, and ships dry when none is on file. NAME A MOOD — upbeat / calm / warm / epic / tense / playful / elegant / hype / chill / dramatic — to compose one on ANY channel, at the same fee. hermoso_capabilities reports the exact figure as explainerMusicCredits; quote it before you turn a bed on or pick a mood."
      },
      "style": {
        "enum": [
          "cinematic",
          "editorial_collage",
          "flat_vector",
          "stickman",
          "whiteboard",
          "ink_marker",
          "silhouette",
          "storybook",
          "paper_diorama",
          "isometric",
          "claymation",
          "pixel_art",
          "watercolor",
          "fluffy_toy",
          "low_poly",
          "stylized_3d",
          "studio_3d",
          "mannequin"
        ],
        "type": "string",
        "description": "visual style. 'cinematic' (default) is photoreal; the rest are non-photoreal styled looks — editorial_collage (halftone cutouts + marker accents), flat_vector, stickman, whiteboard, ink_marker, silhouette, storybook (gouache), paper_diorama, isometric, claymation, pixel_art, watercolor, fluffy_toy (felted plush), low_poly, stylized_3d (matte clay render), studio_3d (preschool toy 3D on a white sweep — the Kids default), mannequin (clay-render reenactment figures — a History alternate). Ask the user which they want rather than picking silently; a styled pick costs more (see the cost note)."
      },
      "topic": {
        "type": "string",
        "description": "what the explainer should teach or explain — a topic or a short brief"
      },
      "voice": {
        "type": "string",
        "description": "narration voice name — omit for the default warm read"
      },
      "channel": {
        "enum": [
          "explainer",
          "history",
          "kids",
          "fairytale"
        ],
        "type": "string",
        "description": "the CHANNEL TYPE — it sets the pacing, the narration register and the default look, and is orthogonal to `style` (a named style always wins): explainer (casual second-person, fast cuts), history (witty chronological retelling / documentary), kids (fastest, question-first, warm teacher), fairytale (slow, atmospheric myth or folklore). Default 'explainer'."
      },
      "endCard": {
        "type": "boolean",
        "description": "append the branded end card. DEFAULT FALSE — set true ONLY when the user asks for one"
      },
      "upscale": {
        "type": "number",
        "description": "optional FINAL upscale — 2 doubles each side, 4 quadruples. Captions and the end card are burned BEFORE it so they upscale with the frame. It is priced BY LENGTH and it is the expensive part — several times the cost of rendering the film itself. hermoso_capabilities reports the exact figures per length as explainerUpscaleCredits. Never turn it on unasked: quote the number and let the user choose."
      },
      "captions": {
        "type": "boolean",
        "description": "turn ON-SCREEN TEXT on. DEFAULT FALSE, and leave it false unless the user asks — the narration already says the point and the pictures carry it, so the clean film is the better default. `captions:true` on its own burns SUBTITLES (see below), because that is what a caption is for: showing what is being said when the phone is on mute. Slim white CAPS, thin black outline, bottom safe band, no plate, no box."
      },
      "brandName": {
        "type": "string",
        "description": "brand name for the end card — omit to leave it unbranded"
      },
      "subtitles": {
        "type": "boolean",
        "description": "which on-screen text, once `captions` is on. LEAVE IT UNSET (or true) for SUBTITLES — every spoken word, in order, timed to the narration; free, no extra render, no extra credits, and there is NO cue limit, so the whole film is subtitled however long it runs (at most 5 words / 32 characters a line). Set it FALSE only if the user explicitly wants section HEADINGS instead: one short summary label held over each ~7-15s section. That is NOT what is being said — it is a label about it — so it is the wrong answer to \"add captions\" and to anyone watching on mute. `subtitles:true` also implies `captions:true`. TIMING: each cue is anchored to that section’s REAL measured narration length and distributed inside the section by character count — exact at every section boundary, approximate to a few tenths of a second within one. It is not a word-level speech clock, so never promise frame-accurate sync."
      },
      "aspectRatio": {
        "enum": [
          "9:16",
          "16:9",
          "1:1",
          "4:5",
          "3:4"
        ],
        "type": "string",
        "description": "'9:16' default"
      },
      "frameDensity": {
        "enum": [
          "standard",
          "lean",
          "minimal"
        ],
        "type": "string",
        "description": "how many pictures per second of narration, and therefore what it costs. 'standard' (default) is a frame about every 1.5s — the density a stills film needs to read as a film rather than a slideshow; 'lean' is one about every 2.5s (the longest hold that still reads as a film, ~40% of the frames and ~40% of the cost); 'minimal' is ONE picture per narration section, which is cheapest and is frankly a slideshow. Only drop below the default if the user asked for something cheaper."
      },
      "durationSeconds": {
        "type": "number",
        "description": "target length 20-120s (default 60); drives the section count — ~10s of narration each, 3-8 sections"
      }
    }
  }

  arguments 99 lines copy
• product_sizzle unknown never probed

  Render an 18-30s music-led PRODUCT SIZZLE: ONE 15s Seedance 2.0 hero clip of the product, diced into fast cuts and intercut with typeset spec/CTA cards on a brand-coloured grain background, mixed to a music bed. Faceless by design — no people, no voiceover, no spoken lines; the cards carry every word, so nothing is left to a video model's spelling. Pass a real packshot as refImage or the label will not be yours. EXPENSIVE — the hero clip is the only paid leg and it is a full 15s Seedance render: ≈1,040 credits at the DEFAULT 1080p, ≈470 at 720p, ≈220 at 480p, ≈4,130 at 4k (call hermoso_capabilities for the live seedance-2 per-duration numbers; the dicing and the cards are free, and the music bed is already included in the quoted figure). Confirm the spend with the user before calling. For a talking/UGC ad use render_ad or generate_avatar; for a cheap deterministic format use make_template_ad.

  mcp-tool

  123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "prompt"
    ],
    "properties": {
      "cta": {
        "type": "string",
        "description": "closing CTA line, ≤30 chars"
      },
      "specs": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "up to 4 spec lines for the typeset cards, ≤26 chars each"
      },
      "prompt": {
        "type": "string",
        "description": "what the sizzle should show — the product, the setting, the look"
      },
      "seconds": {
        "type": "number",
        "description": "finished length, clamped to 18-30s (default 25). The PAID hero render is always 15s regardless — this only changes how the cuts and cards are packed"
      },
      "refImage": {
        "type": "string",
        "description": "product packshot URL that anchors the real label — strongly recommended"
      },
      "brandName": {
        "type": "string",
        "description": "brand name on the cards — defaults to the workspace brand"
      },
      "musicMood": {
        "type": "string",
        "description": "music-bed mood, e.g. driving / cinematic / upbeat"
      },
      "resolution": {
        "enum": [
          "480p",
          "720p",
          "1080p",
          "4k"
        ],
        "type": "string",
        "description": "hero-clip resolution and therefore the whole cost — DEFAULT '1080p' (≈1,040 credits); '720p' ≈470, '480p' ≈220, '4k' ≈4,130"
      },
      "aspectRatio": {
        "type": "string",
        "description": "'9:16' default; anything the seedance-2 catalog entry does not list falls back to 9:16"
      }
    }
  }

  arguments 54 lines copy
• generate_video unknown never probed

  Render a RAW video clip from your own prompt and return its served mp4 URL. For finished brand ADS prefer render_ad (it runs the Studio quality pipeline — composited text, clean speech, end card, music); use this for raw/experimental clips or precise manual control. ONE generation = one continuous clip up to the model’s longest listed duration — the longest-clip model in the catalog today renders a full multi-beat spot of up to 30 SECONDS in ONE unbroken take with native synchronized audio, so never assume a generic 8–10s cap and never stitch something that fits one clip; durationSeconds must be one of the model’s durations from hermoso_capabilities, which is the live list. TO GET A SPECIFIC MODEL, NAME IT in `model`: an unnamed render is routed by the server’s own auto-pool, which is narrower than the catalog, so the longest-clip and highest-resolution models are reached by naming them and not by omitting the field. Renders take 1–3 min. refImage anchors the opening frame; ttsScript adds a voiceover. AUDIO IS NOT FREE AND NOT OPTIONAL BY DEFAULT: a clip delivered with no audio of its own gets a music bed composed and CHARGED on top of the render (see musicMood and audio) — on a cheap short draft the bed can cost as much as the clip. Pass refVideo (a clip URL) to EDIT an existing video instead of generating from scratch — the omni engine transforms that clip per your prompt, inheriting the source clip’s canvas + length (aspectRatio/durationSeconds are ignored for an edit). RAW MODEL ACCESS: your prompt is NOT dispatched verbatim by default — a few small guards are appended (packaging/label safety when no reference image rides, a negative prompt on the models that take one, reference-binding lines when references ride) and hex colour codes are rewritten to colour names. Pass raw:true for none of that. raw:true dispatches your prompt to the model BYTE-IDENTICAL — no rewriting, no appended guidance, no negative prompt, no brand references attached on your behalf. Credits, the durable delivery of the finished asset and the per-model validation are unchanged. Spends credits (Starter plan is video-blocked server-side).

  mcp-tool

  123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "prompt"
    ],
    "properties": {
      "raw": {
        "type": "boolean",
        "description": "RAW MODEL ACCESS: dispatch this prompt to the model BYTE-IDENTICAL — no appended packaging/label guidance, no negative prompt, no reference-binding lines, no hex-to-colour-name rewrite. Use it when you want the model itself rather than Hermoso's render craft. Two vendor-required fixes still apply: extra @ImageN tokens are dropped and an over-long prompt is trimmed at a sentence. Billing, durable delivery and per-model validation are unchanged."
      },
      "loop": {
        "type": "boolean",
        "description": "true = a seamless loop whose last frame flows back into its first. Only models with loop true in hermoso_capabilities; needs refImage and cannot be combined with endImage."
      },
      "audio": {
        "type": "boolean",
        "description": "default true. false = render SILENT: no native model audio, no music bed, and no bed charge held or billed. This is the ONLY way to decline the automatic bed (see musicMood) — leave it alone for anything that should have sound, and do not combine it with ttsScript."
      },
      "model": {
        "type": "string",
        "description": "video model id from hermoso_capabilities; a named model is never swapped without asking. Omit to let the router pick"
      },
      "shots": {
        "type": "array",
        "items": {
          "type": "object",
          "required": [
            "prompt",
            "seconds"
          ],
          "properties": {
            "prompt": {
              "type": "string",
              "description": "what happens in this shot"
            },
            "seconds": {
              "type": "integer",
              "maximum": 15,
              "minimum": 1,
              "description": "this shot’s length in whole seconds"
            }
          }
        },
        "description": "MULTI-SHOT: one clip cut into these shots, in order. The seconds must add up to a length the model renders; replaces `prompt` (send either). Only models with multiShot true in hermoso_capabilities."
      },
      "extend": {
        "type": "boolean",
        "description": "true = EXTEND refVideo: the same clip continues per your prompt for durationSeconds more (each model’s extend.minSeconds..maxSeconds in hermoso_capabilities), delivered as ONE clip, source then continuation. Needs model named (a model with extend in hermoso_capabilities)."
      },
      "prompt": {
        "type": "string",
        "description": "the video prompt / shot description (for a refVideo edit, this is the transformation instruction)"
      },
      "endImage": {
        "type": "string",
        "description": "local path or URL of the LAST frame: the clip travels from refImage (required with it) to this image. Only models with endFrame true in hermoso_capabilities take it; any other named model is refused by name, nothing charged."
      },
      "refImage": {
        "type": "string",
        "description": "local path or URL to anchor the first frame"
      },
      "refVideo": {
        "type": "string",
        "description": "URL of an existing video to EDIT rather than generate from scratch — the clip is transformed per your prompt, inheriting the SOURCE clip’s canvas (aspect ratio) and, on every model hermoso_capabilities marks `sourceLength`, its LENGTH too: those endpoints have no duration parameter, their listed `durations` are the per-second price ladder, and a durationSeconds you send is reported back as unused rather than silently dropped. Trim the source to change the length. Omit `model` for the default editor, or name a model whose videoEdit is true in hermoso_capabilities (a named model that cannot edit is refused, nothing charged); refImage rides along as the look of what the edit adds. With extend:true this is instead the clip to EXTEND. Omit to generate a fresh clip."
      },
      "ttsVoice": {
        "type": "string",
        "description": "voice name, e.g. Rachel / George"
      },
      "musicMood": {
        "type": "string",
        "description": "WHICH mood the music bed is composed in (upbeat / calm / warm / epic / tense / playful / elegant / hype / chill / dramatic). It does NOT decide WHETHER there is one: a clip that comes back with no audio track — every model hermoso_capabilities lists as \"silent\", plus any audio model that returned mute — gets a bed composed and CHARGED automatically, at the flat per-track fee hermoso_capabilities reports as explainerMusicCredits, and omitting this field only means the mood defaults to \"warm\". Pass audio:false for a genuinely silent clip with no bed and no bed charge."
      },
      "refImages": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "SEVERAL reference images (local paths or URLs) — a person, products, a place — that must all appear in the clip. Only models whose `refs.max` in hermoso_capabilities is above 1 use more than one, and each uses at most that many; with `refs.promptAddressed` true, name them in your prompt as Image 1, Image 2… in this order. minimax-h3-max-ref takes up to 9 and keeps each one as a reference rather than a first frame. On a model that takes one image, only the first is used."
      },
      "ttsScript": {
        "type": "string",
        "description": "voiceover script to speak"
      },
      "cameraMove": {
        "enum": [
          "orbit",
          "orbit_left",
          "orbit_half",
          "orbit_full",
          "rise",
          "crane_up",
          "push_in",
          "pull_back",
          "reveal"
        ],
        "type": "string",
        "description": "A named camera move around the still in refImage, spelled exactly as the enum gives it: an orbit (a quarter turn, the default), orbiting left, a half turn or a full turntable, a rise, a crane up, a push in, a pull back, or a reveal. Only the camera-controls model renders one (minimax-h3-max-camera, listed with its moves in hermoso_capabilities): pass it with model omitted and that model is picked, or with that model named; any other named model is refused by name with nothing charged. Needs refImage."
      },
      "resolution": {
        "enum": [
          "480p",
          "720p",
          "1080p",
          "4k"
        ],
        "type": "string",
        "description": "'1080p' default (what we ship and bill for); '480p'/'720p' = cheaper draft passes, '4k' = premium final delivery (more credits). NOT EVERY MODEL OFFERS EVERY TIER — this enum is what the tool accepts, and each model's OWN `resolutions` list in hermoso_capabilities is what it can actually render. Ask for a tier the chosen model does not list and it is rendered at that model's best available tier instead, with nothing in the reply saying so — so check `resolutions` before promising anyone 1080p or 4k."
      },
      "aspectRatio": {
        "type": "string",
        "description": "default '9:16'"
      },
      "interactionId": {
        "type": "string",
        "description": "with extend:true on an Omni model: the interactionId returned by an earlier render on that model — continues it from its own stored context instead of re-uploading refVideo."
      },
      "durationSeconds": {
        "type": "number",
        "description": "length of THIS ONE clip in seconds — pick one of the CHOSEN model’s listed durations from hermoso_capabilities (never a generic guess: the lists differ per model, from 4–8s on the short models up to 30s on the longest-clip one). This is a single continuous generation, so it CANNOT exceed that model’s longest clip: a longer ask is REFUSED with nothing rendered and nothing charged (it is never quietly truncated). Past ~15s only the long-clip models qualify, and an unnamed render is routed by the narrower auto-pool — so NAME the model in `model` when you are asking for a long single take. For a spot longer than any one clip, use plan_ad with durationSeconds then render_ad, which stitches acts of at most one model clip each (on a 15s-clip model, 40s = 15+15+10)."
      },
      "cameraTrajectory": {
        "type": "array",
        "items": {
          "type": "object",
          "required": [
            "time",
            "azimuth",
            "elevation",
            "distance"
          ],
          "properties": {
            "time": {
              "type": "number",
              "maximum": 1,
              "minimum": 0,
              "description": "when this pose is reached, 0 = start of the clip, 1 = end"
            },
            "azimuth": {
              "type": "number",
              "description": "horizontal angle around the subject in degrees (0 = where the still was taken; the sign turns the camera the other way; at most 32 full turns of total travel)"
            },
            "distance": {
              "type": "number",
              "description": "distance from the subject in scene units, 1 = the distance of the still; smaller is closer",
              "exclusiveMinimum": 0
            },
            "elevation": {
              "type": "number",
              "maximum": 90,
              "minimum": -90,
              "description": "vertical angle in degrees, -90 (below) to 90 (straight above)"
            }
          }
        },
        "maxItems": 12,
        "minItems": 2,
        "description": "Your own ordered camera path, 2 to 12 keyframes, for the camera-controls model only (same rule as cameraMove; overrides it). The first pose is held until its time and the last pose is held to the end. A value outside these bounds is refused by name, nothing charged."
      }
    }
  }

  arguments 162 lines copy
• generate_avatar unknown never probed

  Render a TALKING-AVATAR / creator lip-sync clip from a portrait image + a script. Blocks until done (1–3 min). Requires the avatar capability (canAvatar in hermoso_capabilities). Spends credits.

  mcp-tool

  1234567891011121314151617181920212223242526

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "image",
      "script"
    ],
    "properties": {
      "image": {
        "type": "string",
        "description": "local path or URL of the presenter portrait"
      },
      "voice": {
        "type": "string",
        "description": "voice name (Rachel/Sarah/George/Adam)"
      },
      "script": {
        "type": "string",
        "description": "the words the avatar speaks"
      },
      "resolution": {
        "type": "string",
        "description": "'1080p' (default) or '480p'/'720p' draft"
      }
    }
  }

  arguments 26 lines copy
• stitch_video unknown never probed

  Render a multi-scene STITCHED video (≥2 scenes) — ONLY for spots LONGER than ONE clip of the chosen model. A multi-beat ad that FITS one clip renders better and cheaper as ONE single-pass generate_video/render_ad (a single generation carries the whole hook→demo→payoff arc) — never stitch those. What fits is the model’s own maximum from hermoso_capabilities, not a fixed number: 15s on most models, 30s on the longest-clip one, so a 30s spot need not be stitched at all if you name that model. Blocks until done. Spends credits.

  mcp-tool

  12345678910111213141516171819202122232425262728293031323334353637383940414243

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "scenes"
    ],
    "properties": {
      "model": {
        "type": "string",
        "description": "video model id from hermoso_capabilities — omit to let the router pick"
      },
      "voice": {
        "type": "string",
        "description": "voiceover voice name, e.g. Rachel / George"
      },
      "scenes": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {},
          "additionalProperties": {}
        },
        "minItems": 2,
        "description": "array of scene objects (visual + optional voiceover/seconds)"
      },
      "voiceover": {
        "type": "string",
        "description": "full voiceover script spoken across the scenes"
      },
      "resolution": {
        "type": "string",
        "description": "720p (default), 1080p for full detail, or 480p for a cheaper draft"
      },
      "aspectRatio": {
        "type": "string",
        "description": "output aspect ratio, e.g. 9:16 (default) / 1:1 / 16:9"
      },
      "durationSeconds": {
        "type": "number",
        "description": "total spot length in seconds (defaults to the sum of the scenes’ seconds)"
      }
    }
  }

  arguments 43 lines copy
• get_job unknown never probed

  Poll a render job by id. Returns status (queued|running|done|error), progress, and on done the served media URL. Renders take 1–3 minutes: keep calling this until done/error without asking the user — several calls is normal, not a stall. An id that does not exist on this account answers status "not_found" — that is FINAL: stop polling it, and do not re-fire the render (that double-charges).

  mcp-tool

  12345678910111213

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "id"
    ],
    "properties": {
      "id": {
        "type": "string",
        "description": "the job id, e.g. job_xxx"
      }
    }
  }

  arguments 13 lines copy
• list_skills unknown never probed

  List the bundled Hermoso SKILLS — multi-step workflow instructions (SKILL.md) that orchestrate the other tools (research an ad space, plan+render a finished ad, product photoshoot, raw generation) — plus the in-app strategy skills and creative recipes. Call get_skill to load a bundle. Read-only, free.

  mcp-tool

  12345

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {}
  }

  arguments 5 lines copy
• get_skill unknown never probed

  Load a bundled skill’s full SKILL.md workflow instructions by name (from list_skills). Follow the loaded instructions to run that workflow with the other tools. Read-only, free.

  mcp-tool

  12345678910111213

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "name"
    ],
    "properties": {
      "name": {
        "type": "string",
        "description": "bundle name from list_skills, e.g. hermoso-generate"
      }
    }
  }

  arguments 13 lines copy
• save_skill unknown never probed

  Save a reusable custom SKILL — a named creative directive/playbook applied to future ads (a hook formula, a UGC recipe, a compliance rule, a named specialist persona like “our founder-story style” or “short-form ad strategist”). Distill an imperative, self-contained directive. Merges into the workspace Skills library (list_skills shows built-ins + your custom skills).

  mcp-tool

  123456789101112131415161718

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "name",
      "directive"
    ],
    "properties": {
      "name": {
        "type": "string",
        "description": "short skill name, e.g. “Founder-story hook”"
      },
      "directive": {
        "type": "string",
        "description": "the full instruction the skill applies when used (1–6 sentences, imperative)"
      }
    }
  }

  arguments 18 lines copy
• delete_skill unknown never probed

  Delete one of the workspace’s CUSTOM skills by id (from list_skills). Built-in skills/recipes can’t be deleted. Minor + re-creatable, so no confirm needed.

  mcp-tool

  12345678910111213

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "id"
    ],
    "properties": {
      "id": {
        "type": "string",
        "description": "the custom skill id (from list_skills)"
      }
    }
  }

  arguments 13 lines copy
• list_memory unknown never probed

  List the durable facts & preferences saved in this workspace’s Memory (what the studio remembers about the brand, audience, taste, and do/don’t rules) — the same Memory the web app shows. These shape every future ad. Read-only, free.

  mcp-tool

  1234567891011121314

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "limit": {
        "type": "number",
        "description": "max items (default 50, max 200)"
      },
      "category": {
        "type": "string",
        "description": "filter to one bucket (Brand/Audience/Taste/Do/Don’t/Preference)"
      }
    }
  }

  arguments 14 lines copy
• remember unknown never probed

  Save a durable fact or PREFERENCE about the brand, audience, or the user’s creative TASTE (e.g. “audience is first-time homebuyers”, “prefers bold lime accents”, “always captions off”) into the workspace Memory so it shapes FUTURE ads. For lasting things, not one-off requests. Merges into the existing Memory (never overwrites); de-dupes on identical text. NEVER how Hermoso, a tool, a connector or a platform API behaves (what a call returns, errors, permissions, limits, ids) and never a phone number or email — those are refused.

  mcp-tool

  1234567891011121314151617

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "text"
    ],
    "properties": {
      "text": {
        "type": "string",
        "description": "the fact/preference, concise"
      },
      "category": {
        "type": "string",
        "description": "short bucket: Brand, Audience, Taste, Do, Don’t, or Preference (default General)"
      }
    }
  }

  arguments 17 lines copy
• forget unknown never probed

  Delete a saved Memory item by its id (from list_memory). Records a cross-device delete so it doesn’t come back. Minor + re-creatable (you can remember it again), so no confirm needed.

  mcp-tool

  12345678910111213

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "id"
    ],
    "properties": {
      "id": {
        "type": "string",
        "description": "the memory item id (from list_memory)"
      }
    }
  }

  arguments 13 lines copy
• tidy_memory unknown never probed

  Clean up and consolidate the workspace Memory: drops entries that are about how Hermoso, a tool, a connector or a platform API behaves (product behaviour, not the brand), drops phone numbers and emails, and merges near-duplicate facts into one sentence each. Call with no argument to get the PROPOSAL (what would be removed and merged, with reasons) — nothing changes. Call again with confirm:true to apply it through the same typed writers the app uses (deletes carry tombstones so they stay deleted on every device). One small model call; a few credits.

  mcp-tool

  12345678910

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "confirm": {
        "type": "boolean",
        "description": "true to APPLY the proposal; omit to only see it"
      }
    }
  }

  arguments 10 lines copy
• list_swipefile unknown never probed

  List this workspace's SWIPEFILE — the saved-ad research board: every named collection and the ads/creatives kept in it (advertiser, headline, body copy, media URL, platform, when it was saved, and any taste tags). The SAME board the web app's Swipefile tab shows. Use it to answer "what have we saved?", to mine the user's own taste before planning an ad, or to find a reference to remix. Read-only, free.

  mcp-tool

  1234567891011121314

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "limit": {
        "type": "number",
        "description": "max ads to return (default 50, max 500)"
      },
      "collection": {
        "type": "string",
        "description": "only list ads in this collection (by name or id) — omit for every collection"
      }
    }
  }

  arguments 14 lines copy
• save_to_swipefile unknown never probed

  Save one or more ads/creatives to a named SWIPEFILE collection, creating the collection if it does not exist — the headless twin of the ♥ on every ad card in the web app. Use it whenever research turns up something worth keeping: a competitor ad from search_meta_ads / pull_competitor_ads, an organic post, or one of your own renders. Saved ads persist to the workspace board the web Swipefile tab shows, and feed the taste signal every future ad is planned against. De-dupes: re-saving the same ad (same key/link/media) MOVES it into the named collection instead of duplicating it. Free.

  mcp-tool

  1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "collection",
      "items"
    ],
    "properties": {
      "items": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "key": {
              "type": "string",
              "description": "a stable id for this ad if you have one (an ad_archive_id, creativeId, …). Omit and one is derived from the link/media so re-saving is idempotent"
            },
            "body": {
              "type": "string",
              "description": "the ad copy"
            },
            "link": {
              "type": "string",
              "description": "link to the ad in its library / the destination URL"
            },
            "image": {
              "type": "string",
              "description": "image URL"
            },
            "title": {
              "type": "string",
              "description": "headline / hook"
            },
            "video": {
              "type": "string",
              "description": "video URL"
            },
            "pageName": {
              "type": "string",
              "description": "alias of advertiser"
            },
            "platform": {
              "type": "string",
              "description": "where it ran — 'meta', 'google', 'linkedin', 'tiktok', 'generated', …"
            },
            "page_name": {
              "type": "string",
              "description": "alias of advertiser: the field search_meta_ads returns, accepted as-is"
            },
            "advertiser": {
              "type": "string",
              "description": "the brand running the ad"
            }
          },
          "additionalProperties": {}
        },
        "minItems": 1,
        "description": "the ads to save"
      },
      "collection": {
        "type": "string",
        "description": "the collection name — an existing one, or a new one to create"
      }
    }
  }

  arguments 65 lines copy
• update_saved_creator unknown never probed

  Set the OUTREACH STATUS and/or a NOTE on a creator already saved in the swipefile (find_creators → save_to_swipefile, or the ♥ on a creator card). Status is one of new | contacted | replied | booked | passed. The note is free text (deal terms, rate, what was sent). Reads back the updated row. Use list_swipefile to find the key. Free.

  mcp-tool

  12345678910111213141516171819202122232425262728

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "key"
    ],
    "properties": {
      "key": {
        "type": "string",
        "description": "the saved row's key from list_swipefile, e.g. tiktok:handle"
      },
      "note": {
        "type": "string",
        "maxLength": 2000,
        "description": "replaces the existing note; pass \"\" to clear it"
      },
      "status": {
        "enum": [
          "new",
          "contacted",
          "replied",
          "booked",
          "passed"
        ],
        "type": "string"
      }
    }
  }

  arguments 28 lines copy
• list_playbooks unknown never probed

  List the PLAYBOOKS saved in this workspace — the reusable strategy cards (winning hooks, angles, formats and the concrete plays to run) kept from teardowns, angle mining and creatives worth repeating. The same Playbooks the web app's Playbooks tab lists. Read one before planning an ad so you re-run what already worked instead of starting cold. Read-only, free.

  mcp-tool

  1234567891011121314

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "full": {
        "type": "boolean",
        "description": "true to return every hook/angle/play in the text, not just the headline counts"
      },
      "limit": {
        "type": "number",
        "description": "max playbooks to return (default 25, max 100)"
      }
    }
  }

  arguments 14 lines copy
• save_playbook unknown never probed

  Save a reusable PLAYBOOK — the strategy takeaways worth re-running: the hooks that work, the angles, the formats, and the concrete plays. Use it to keep what a competitor_teardown or mine_angles just found, or to bank a creative you want to repeat. Lands in the same Playbooks library the web app lists, runs and manages. Distinct from save_skill (a directive applied to every ad) and from the swipefile (raw saved creative). Free.

  mcp-tool

  12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "name"
    ],
    "properties": {
      "name": {
        "type": "string",
        "description": "the playbook headline — what it is, in a few words"
      },
      "brand": {
        "type": "string",
        "description": "which brand this is for (defaults to the workspace brand)"
      },
      "hooks": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "the opening hooks worth reusing, verbatim"
      },
      "plays": {
        "type": "array",
        "items": {
          "type": "object",
          "required": [
            "title"
          ],
          "properties": {
            "title": {
              "type": "string"
            },
            "detail": {
              "type": "string"
            }
          },
          "additionalProperties": {}
        },
        "description": "the concrete plays to run ({title, detail}) — the actionable half"
      },
      "angles": {
        "type": "array",
        "items": {
          "type": "object",
          "required": [
            "title"
          ],
          "properties": {
            "title": {
              "type": "string"
            },
            "detail": {
              "type": "string"
            }
          },
          "additionalProperties": {}
        },
        "description": "the persuasion angles ({title, detail})"
      },
      "source": {
        "type": "string",
        "description": "where it came from, e.g. “teardown · Ridge”"
      },
      "formats": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "the formats/recipes this plays best in (e.g. ugc_selfie, cinematic, static)"
      }
    }
  }

  arguments 73 lines copy
• delete_playbook unknown never probed

  Delete a saved playbook by id (from list_playbooks). Records a cross-device delete so it does not come back on the next sync. Minor + re-creatable, so no confirm needed.

  mcp-tool

  12345678910111213

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "id"
    ],
    "properties": {
      "id": {
        "type": "string",
        "description": "the playbook id (from list_playbooks)"
      }
    }
  }

  arguments 13 lines copy
• list_creators unknown never probed

  List this workspace’s SAVED CREATORS — the reusable on-camera cast (AI creators made here, a person pulled from a social profile, a consented photo upload). Read-only, FREE. Each entry gives the name, the PORTRAIT URL, where the portrait came from and whether a real person’s likeness consent is on file, how many extra pose plates exist, and any chosen or cloned voice. TO PUT ONE IN A FINISHED AD, pass their id or name as render_ad’s `creator` — that casts them for the whole spot (and skips the character-portrait render, so it costs less than not casting anyone). THE PORTRAIT URL IS THE REUSE HANDLE for the raw lanes — pass it as generate_avatar’s `image` (a talking clip of them), generate_video’s `refImage` (they star in the scene), recast_motion’s `image` (they perform a reference clip’s motion), or generate_image’s `refImages`. CALL THIS BEFORE OFFERING TO GENERATE A NEW PERSON: re-casting somebody the workspace already has keeps the SAME face across every ad, while a fresh person costs credits and breaks that continuity. An empty answer means the workspace genuinely has no cast yet — say so and offer generate_avatar / save_creator, never invent a roster.

  mcp-tool

  12345678910

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "limit": {
        "type": "number",
        "description": "max creators to return (default 24)"
      }
    }
  }

  arguments 10 lines copy
• save_creator unknown never probed

  Add a portrait to this workspace’s reusable CAST so the SAME person can star in future ads — the headless twin of the app’s ＋ ▸ Pick a creator ▸ save. Pass the portrait’s public url (a generate_image render of a person, a headshot, any public photo) plus a name to call them by; from then on list_creators returns them and their url can be re-passed to generate_avatar / generate_video / recast_motion. Saving is FREE and renders nothing. LIKENESS — `source` says what the portrait IS: leave it "generated" for an AI-made person, and use "upload"/"social" ONLY for a REAL person. Pass consented:true only when the user has told you that person agreed to their likeness being used; never assert that on their behalf.

  mcp-tool

  12345678910111213141516171819202122232425262728293031323334353637383940414243444546

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "name",
      "image"
    ],
    "properties": {
      "look": {
        "type": "string",
        "description": "their canonical wardrobe/appearance in words — reused to hold the look steady across ads"
      },
      "name": {
        "type": "string",
        "description": "what to call this creator (e.g. “Sarah”) — list_creators and the app’s picker match on it"
      },
      "image": {
        "type": "string",
        "description": "public https url of the portrait (an existing render’s url, or any public photo). Not a local file path — upload it with upload_file first and save the url that returns"
      },
      "poses": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "up to 4 extra full-body / angle plates of the SAME person (public urls) — they make a wider shot hold the identity"
      },
      "voice": {
        "type": "string",
        "description": "a default voice name for this persona (engines + voices are in hermoso_capabilities)"
      },
      "source": {
        "enum": [
          "generated",
          "upload",
          "social"
        ],
        "type": "string",
        "description": "\"generated\" (default) = an AI-made person; \"upload\" / \"social\" = a REAL person"
      },
      "consented": {
        "type": "boolean",
        "description": "REAL people only: the user has confirmed that person consented to their likeness being used in ads"
      }
    }
  }

  arguments 46 lines copy
• delete_creator unknown never probed

  Remove a saved creator from this workspace’s cast by id (from list_creators). Records a cross-device delete so they don’t reappear on the user’s other devices. It only drops the roster entry — ads already rendered with that person are untouched — and the same portrait can be saved again with save_creator, so no confirm is needed.

  mcp-tool

  12345678910111213

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "id"
    ],
    "properties": {
      "id": {
        "type": "string",
        "description": "the creator id (from list_creators)"
      }
    }
  }

  arguments 13 lines copy
• update_brand unknown never probed

  Patch SPECIFIC fields of the workspace brand profile (name, domain, sells, summary, category, audience, positioning, voice, style, goal) WITHOUT overwriting the rest — a read-modify-write on the saved brand. Use for “change our voice to playful”, “we sell to dentists now”. To onboard a brand from scratch, use draft_brand. Only pass the fields you’re changing.

  mcp-tool

  123456789101112131415161718192021222324252627282930313233343536373839404142

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "goal": {
        "type": "string",
        "description": "current marketing goal"
      },
      "name": {
        "type": "string"
      },
      "sells": {
        "type": "string",
        "description": "what the brand sells"
      },
      "style": {
        "type": "string",
        "description": "visual style — palette, typography, aesthetic"
      },
      "voice": {
        "type": "string",
        "description": "brand voice/tone"
      },
      "domain": {
        "type": "string",
        "description": "website domain"
      },
      "summary": {
        "type": "string",
        "description": "one-line description"
      },
      "audience": {
        "type": "string"
      },
      "category": {
        "type": "string"
      },
      "positioning": {
        "type": "string"
      }
    }
  }

  arguments 42 lines copy
• store_get unknown never probed

  Read one of this workspace’s data stores by key, for visibility into what the app holds — playbooks, swipefile, saved locations, avatars, creations, chats, brand, memory, skills. Read-only, free. Allowed keys: heist.memory.v1, heist.skills.v1, heist.playbooks.v1, heist.avatars.v1, heist.locations.v1, heist.chats.v1, heist.creations.v1, heist.assets.v1, heist.brand.v1, adInspo.swipefile.v1. (The typed tools — list_memory / list_skills / get_brand — are friendlier for those; use store_get for the rest.)

  mcp-tool

  1234567891011121314151617

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "key"
    ],
    "properties": {
      "key": {
        "type": "string",
        "description": "the store key to read (one of the allowlisted keys)"
      },
      "limit": {
        "type": "number",
        "description": "max array items to return (default 50)"
      }
    }
  }

  arguments 17 lines copy
• get_settings unknown never probed

  Read this account's app settings — the LANGUAGE Hermoso writes ads, copy and answers in, the app appearance (theme), and whether the weekly competitor-watch email is on. Same settings as the web app's Settings pane. Read-only, free.

  mcp-tool

  12345

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {}
  }

  arguments 5 lines copy
• update_settings unknown never probed

  Change this account's app settings. language = the language EVERY ad, script, plan and answer is written in from now on (say the language in plain English, e.g. "German", "Japanese", "Brazilian Portuguese") — it applies to renders made over MCP as well as in the app. theme = the app's appearance, "dark" or "light". watchEmail = the weekly competitor-watch email on/off. Only pass what you are changing. Account-wide (every brand), and it takes effect on the next call.

  mcp-tool

  12345678910111213141516171819202122

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "theme": {
        "enum": [
          "dark",
          "light"
        ],
        "type": "string",
        "description": "app appearance"
      },
      "language": {
        "type": "string",
        "description": "language for generated ads, copy and answers — e.g. \"English\", \"German\", \"Japanese\""
      },
      "watchEmail": {
        "type": "boolean",
        "description": "weekly competitor-watch email on/off"
      }
    }
  }

  arguments 22 lines copy
• list_connectors unknown never probed

  List the third-party accounts connected to this workspace (Meta, Google Ads, Google Drive/Sheets/Docs, YouTube, LinkedIn, OneDrive, Slack, …) — provider, status and the connected account label — PLUS which providers are available to connect. IT ALSO FLAGS A CONNECTION WHOSE PERMISSIONS ARE OUT OF DATE: a provider writes its granted permission set into the token at consent time, so a connection authorized before a permission was approved does not carry it and never will — those calls are refused by the provider and no retry or wait can change it. Check this FIRST when a connected provider starts refusing things. The fix is a browser: the user reconnects under Workspace ▸ Connectors. A paste-a-key account needs no browser at all: connect_connector connects it from here if the user prefers that to the app. Read-only, free.

  mcp-tool

  12345

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {}
  }

  arguments 5 lines copy
• list_connector_accounts unknown never probed

  Show every identity a connected account can act as, and which ones this BRAND is currently allowed to use — Facebook Pages + Instagram + Meta ad accounts, Google Ads customers, LinkedIn company Pages (and the personal profile), Pinterest ad accounts, Microsoft Advertising accounts. One person often administers several; only the ticked ones can be posted to or spent from. Call this before set_connector_accounts, and let the USER pick — never guess. Providers: tiktok, x, youtube, threads, bluesky, telegram, reddit, pinterest, instagram, meta, google_ads, linkedin, pinterest_ads, linkedin_ads, reddit_ads, apple_ads, microsoft_ads, google_business, google_analytics, snapchat_ads, x_ads, tiktok_ads, google_tag_manager, google_search_console, bing_webmaster. Read-only, free.

  mcp-tool

  12345678910111213141516171819202122232425262728293031323334353637383940

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "provider"
    ],
    "properties": {
      "provider": {
        "enum": [
          "tiktok",
          "x",
          "youtube",
          "threads",
          "bluesky",
          "telegram",
          "reddit",
          "pinterest",
          "instagram",
          "meta",
          "google_ads",
          "linkedin",
          "pinterest_ads",
          "linkedin_ads",
          "reddit_ads",
          "apple_ads",
          "microsoft_ads",
          "google_business",
          "google_analytics",
          "snapchat_ads",
          "x_ads",
          "tiktok_ads",
          "google_tag_manager",
          "google_search_console",
          "bing_webmaster"
        ],
        "type": "string",
        "description": "which connector’s accounts to list"
      }
    }
  }

  arguments 40 lines copy
• set_connector_accounts unknown never probed

  Set WHICH of a connector's accounts this brand is allowed to post to and spend from — Facebook Pages / Instagram / Meta ad accounts, Google Ads customers, LinkedIn company Pages (and the personal profile), Pinterest or Microsoft Advertising ad accounts. Pass ids from list_connector_accounts. This REPLACES the current selection: anything you leave out is un-shared, and an EMPTY list shares nothing (publishing then refuses — it fails closed by design, and the server re-verifies every id against the live connection, so an id the account cannot actually reach is rejected rather than saved). Ask the user which accounts they mean; posting as the wrong Page is a public mistake. Providers: tiktok, x, youtube, threads, bluesky, telegram, reddit, pinterest, instagram, meta, google_ads, linkedin, pinterest_ads, linkedin_ads, reddit_ads, apple_ads, microsoft_ads, google_business, google_analytics, snapchat_ads, x_ads, tiktok_ads, google_tag_manager, google_search_console, bing_webmaster. Free.

  mcp-tool

  123456789101112131415161718192021222324252627282930313233343536373839404142434445464748

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "provider",
      "accountIds"
    ],
    "properties": {
      "provider": {
        "enum": [
          "tiktok",
          "x",
          "youtube",
          "threads",
          "bluesky",
          "telegram",
          "reddit",
          "pinterest",
          "instagram",
          "meta",
          "google_ads",
          "linkedin",
          "pinterest_ads",
          "linkedin_ads",
          "reddit_ads",
          "apple_ads",
          "microsoft_ads",
          "google_business",
          "google_analytics",
          "snapchat_ads",
          "x_ads",
          "tiktok_ads",
          "google_tag_manager",
          "google_search_console",
          "bing_webmaster"
        ],
        "type": "string",
        "description": "which connector to scope"
      },
      "accountIds": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "the ids (from list_connector_accounts) this brand may use — an empty array shares nothing"
      }
    }
  }

  arguments 48 lines copy
• disconnect_connector unknown never probed

  Disconnect a third-party account from this workspace (Meta, Google Ads, Google Drive/Sheets/Docs, YouTube, TikTok, LinkedIn, X, Reddit, Pinterest, Google Business, Microsoft Advertising/OneDrive, Slack, …). This always drops the stored credentials, so every tool for that provider stops working immediately and posts/campaigns already published are NOT affected. WHETHER IT ALSO REVOKES THE GRANT AT THE PROVIDER DEPENDS ON THE PROVIDER — a few (Threads, Microsoft) publish no revocation endpoint, so the authorisation stays in place until the user removes it in that provider's own settings. The unconfirmed call reports which it is for this provider (list_connectors also carries it as revokesAtProvider) — relay that verbatim rather than promising a revoke. RECONNECTING NEEDS A BROWSER (the provider's consent screen) — an agent cannot undo this. Name the provider to the user, then call with confirm:true. Use list_connectors for the exact provider ids.

  mcp-tool

  123456789101112131415161718192021

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "provider"
    ],
    "properties": {
      "account": {
        "type": "string",
        "description": "on a channel with several connected accounts (TikTok, X, YouTube, Threads, Bluesky, Telegram, Reddit, Pinterest): remove ONLY this account (@handle or id from list_connector_accounts) and keep the others"
      },
      "confirm": {
        "type": "boolean",
        "description": "REQUIRED true — reconnecting a sign-in account afterwards needs the user's browser; a paste-a-key account is reconnected with connect_connector"
      },
      "provider": {
        "type": "string",
        "description": "provider id exactly as list_connectors reports it, e.g. \"meta\", \"google_ads\", \"youtube\", \"linkedin\""
      }
    }
  }

  arguments 21 lines copy
• connect_connector unknown never probed

  Connect an account that links with a KEY rather than a sign-in screen, from here, with no browser: Stripe, ChatGPT Ads, Apple Ads, Bluesky, Telegram, Bing Webmaster Tools, PostHog, Mixpanel, Amplitude, Slack, Discord, Webhook. Pass provider and fields in that provider's own field names (listed below, * = required). The key is checked live with the provider before anything is saved, exactly as the app's Connectors page checks it, and the reply is read back from the saved connection. OFFER BOTH WAYS AND LET THE USER CHOOSE: a key pasted into this chat stays in this conversation's history, while pasting it in the app (Workspace ▸ Connectors, or the one-click link https://app.hermoso.ai/?connect=<provider>) keeps it out of the chat. Hermoso never repeats a submitted key back. An account that connects through the provider's own sign-in screen (OAuth) cannot be connected here: this answers with the link to hand the user instead. Apple Ads with no key material first generates a signing key pair and returns the public key to register with Apple plus a setupToken to send back. Fields: stripe {apiKey*} · openai_ads {apiKey*} · apple_ads {clientId, teamId, keyId, privateKey, setupToken, orgId} · bluesky {identifier*, appPassword*, pds} · telegram {token*} · bing_webmaster {apiKey*} · posthog {apiKey*, region, host, projectId} · mixpanel {username*, secret*, projectId*, region, workspaceId} · amplitude {apiKey*, secretKey*, region, host} · slack {webhookUrl*} · discord {webhookUrl*} · webhook {webhookUrl*}.

  mcp-tool

  1234567891011121314151617181920212223

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "provider"
    ],
    "properties": {
      "fields": {
        "type": "object",
        "description": "that provider's own field names and values, e.g. {\"apiKey\":\"…\"}; the names for each provider are in the description",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {
          "type": "string"
        }
      },
      "provider": {
        "type": "string",
        "description": "the connector id: stripe, openai_ads, apple_ads, bluesky, telegram, bing_webmaster, posthog, mixpanel, amplitude, slack, discord, webhook"
      }
    }
  }

  arguments 23 lines copy
• leave_connector unknown never probed

  On a connector that several teammates can contribute their OWN account to (see list_connectors — the row reports multiContributor), remove YOURS from this brand: your stored credential is dropped and the accounts you shared stop being shared. Your teammates' accounts on the same connection keep working, and nothing changes at the provider — reconnecting in a browser shares again. Use this instead of disconnect_connector when the connection is not yours to remove: disconnect_connector revokes the grant at the provider and only the person who created the connection may call it.

  mcp-tool

  12345678910111213

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "provider"
    ],
    "properties": {
      "provider": {
        "type": "string",
        "description": "provider id exactly as list_connectors reports it, e.g. \"linkedin\", \"tiktok_ads\", \"meta\""
      }
    }
  }

  arguments 13 lines copy
• list_team unknown never probed

  List the members of the current brand workspace — email, role (admin/member) and status. Read-only, free.

  mcp-tool

  12345

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {}
  }

  arguments 5 lines copy
• invite_member unknown never probed

  Invite someone to this brand workspace by email (role: member = read-only on billing, admin = full). This SENDS a real email invite / share link — an account change. Confirm the exact email + role with the user, then call with confirm:true.

  mcp-tool

  12345678910111213141516171819202122232425

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "email"
    ],
    "properties": {
      "role": {
        "enum": [
          "member",
          "admin"
        ],
        "type": "string",
        "description": "default member"
      },
      "email": {
        "type": "string",
        "description": "the invitee’s email"
      },
      "confirm": {
        "type": "boolean",
        "description": "REQUIRED true — this invites a real person"
      }
    }
  }

  arguments 25 lines copy
• remove_member unknown never probed

  Remove a member from this brand workspace by email — they lose access (you can re-invite them later). Confirm the exact person with the user, then call with confirm:true.

  mcp-tool

  1234567891011121314151617

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "email"
    ],
    "properties": {
      "email": {
        "type": "string",
        "description": "the member’s email"
      },
      "confirm": {
        "type": "boolean",
        "description": "REQUIRED true"
      }
    }
  }

  arguments 17 lines copy
• set_role unknown never probed

  Change a workspace member’s role — admin (full access incl. billing) or member (read-only on billing). A privilege change: confirm the exact person + new role with the user, then call with confirm:true.

  mcp-tool

  1234567891011121314151617181920212223242526

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "email",
      "role"
    ],
    "properties": {
      "role": {
        "enum": [
          "admin",
          "member"
        ],
        "type": "string",
        "description": "the new role"
      },
      "email": {
        "type": "string",
        "description": "the member’s email"
      },
      "confirm": {
        "type": "boolean",
        "description": "REQUIRED true"
      }
    }
  }

  arguments 26 lines copy
• list_jobs unknown never probed

  List the most recent render jobs + how many are currently running, so you can report on or resume in-flight work.

  mcp-tool

  12345

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {}
  }

  arguments 5 lines copy
• list_errors unknown never probed

  The errors actually recorded against this workspace, GROUPED by fingerprint — the same failure at the same call site is one row with a hit count and first/last seen, sorted defects-first. Each row says whose side it is: `ours` (a defect worth fixing), `user` (a refusal we deliberately authored, e.g. not-connected or out-of-credits), or `unknown` (a vendor 4xx we cannot attribute — never guessed). Free text, tokens, emails and creative are redacted before anything is stored, so an input echo shows shapes and lengths, not content. Filter by surface (http/mcp/agent/job/client) or kind. Read-only, 0 credits. Scoped to your own workspace; an operator whose client carries the admin key sees every account.

  mcp-tool

  12345678910111213141516171819202122232425262728293031323334

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "kind": {
        "enum": [
          "ours",
          "user",
          "unknown"
        ],
        "type": "string",
        "description": "'ours' = a defect; 'user' = a refusal we authored; 'unknown' = we could not tell"
      },
      "limit": {
        "type": "number",
        "description": "how many groups to return (default 50, max 200)"
      },
      "since": {
        "type": "string",
        "description": "ISO timestamp — only groups last seen at or after this"
      },
      "surface": {
        "enum": [
          "http",
          "mcp",
          "agent",
          "job",
          "client"
        ],
        "type": "string",
        "description": "where it happened: http (an API route), mcp (an agent tool), agent (the in-app Studio agent), job (an async render/publish), client (a browser crash)"
      }
    }
  }

  arguments 34 lines copy
• error_detail unknown never probed

  One error group in full by fingerprint (from list_errors): every field, plus the most recent redacted occurrences — status, connector, job id, workspace, and a shape-only echo of the inputs. This is what makes a bug reproducible. Read-only, 0 credits.

  mcp-tool

  12345678910111213

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "fingerprint"
    ],
    "properties": {
      "fingerprint": {
        "type": "string",
        "description": "the `fp` value from list_errors"
      }
    }
  }

  arguments 13 lines copy
• find_competitors unknown never probed

  Discover a brand's competitor / similar / adjacent brands from its domain (Claude grounded by web search). mode=competitors (default, excludes the searched company), inspiration (best relevant ads incl. it), or company. 0 credits.

  mcp-tool

  12345678910111213141516171819202122

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "domain"
    ],
    "properties": {
      "mode": {
        "enum": [
          "competitors",
          "inspiration",
          "company"
        ],
        "type": "string",
        "description": "'competitors' (default, excludes the searched company), 'inspiration' (best relevant ads incl. it), or 'company'"
      },
      "domain": {
        "type": "string",
        "description": "the brand domain, e.g. flourish.com"
      }
    }
  }

  arguments 22 lines copy
• pull_competitor_ads unknown never probed

  THE FAST PATH for "show me the ads <brand> is running" — one named brand’s real live ads from the META (Facebook/Instagram) ad library, deduped, sorted, with the right page resolved. A single call, back in a few seconds. Prefer this over research_ads whenever the brand is named. Meta only, deliberately: it has by far the richest creative and is what people mean by "their ads". For Google or LinkedIn specifically, use search_google_ads or search_linkedin_ads. Spends credits.

  mcp-tool

  1234567891011121314151617181920212223242526

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "sort": {
        "type": "string",
        "description": "'longest_running' (default) etc."
      },
      "limit": {
        "type": "number",
        "description": "max ads per platform (default 30)"
      },
      "domain": {
        "type": "string",
        "description": "the advertiser domain"
      },
      "country": {
        "type": "string",
        "description": "2-letter, default 'US'"
      },
      "companyName": {
        "type": "string",
        "description": "the advertiser name"
      }
    }
  }

  arguments 26 lines copy
• set_competitor_watch unknown never probed

  Set (or STOP) this workspace's standing COMPETITOR WATCH — the weekly job that re-checks each named brand's ad libraries and reports what is NEW since last time. The same watch the web app's Ad Spy ▸ Watching tab manages, and the same one the weekly digest email is sent from (turn that email on/off with update_settings({watchEmail})). This REPLACES the whole watched list, it does not add to it — pass every brand you want watched, every time. Max 5 brands (the server trims past that). Pass an EMPTY list to stop the watch entirely, which also clears the findings. Give a `domain` wherever you know one: Google Ads Transparency is looked up BY DOMAIN and is skipped for a brand without one, and the domain is what resolves the right Meta page for a brand with an ambiguous name. The run itself spends credits against the ad libraries (roughly 3 per brand on Meta, 1 each on Google and LinkedIn) and is hard-capped per run server-side, so an oversized watch is trimmed rather than allowed to run away. Setting the list is free; only a run spends. runNow:true runs it once IMMEDIATELY (a background job — it spends now) and then keeps the weekly cadence; leave it off and the first check is a week out. The country and the platform mix are NOT settable here — a re-set inherits whatever the pending run already carried (US / Meta for a watch that has never been configured otherwise). Read the findings back with list_watch_findings.

  mcp-tool

  12345678910111213141516171819202122232425262728293031323334

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "competitors"
    ],
    "properties": {
      "runNow": {
        "type": "boolean",
        "description": "true to run one check immediately (spends credits now) instead of waiting a week for the first one"
      },
      "competitors": {
        "type": "array",
        "items": {
          "type": "object",
          "required": [
            "name"
          ],
          "properties": {
            "name": {
              "type": "string",
              "description": "the brand name, as it advertises"
            },
            "domain": {
              "type": "string",
              "description": "its domain, e.g. ridge.com — required for Google Ads Transparency, and what disambiguates a common brand name on Meta"
            }
          },
          "additionalProperties": {}
        },
        "description": "the brands to watch — the COMPLETE list, replacing whatever was set before. Empty array = stop watching."
      }
    }
  }

  arguments 34 lines copy
• list_watch_findings unknown never probed

  Read what the standing COMPETITOR WATCH has found — the new ads each watched brand has launched since the last check, plus the watch's own state (who is watched, when it last ran, when it runs next, and whether the last run actually succeeded). The same board the web app's Ad Spy ▸ Watching tab renders. Use it to answer "what are our competitors running that's new?", to feed a teardown, or to save something worth keeping with save_to_swipefile. Findings marked `seed:true` are NOT new launches — the first check of a brand has nothing to diff against, so it seeds the board with what that brand is running right now; only later runs surface genuine changes. Read-only and free — it returns the stored results of past runs and never triggers a check (set_competitor_watch({runNow:true}) is what runs one).

  mcp-tool

  1234567891011121314

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "limit": {
        "type": "number",
        "description": "max findings to return (default 25, max 75 — the server keeps at most 75, and at most 15 per brand)"
      },
      "competitor": {
        "type": "string",
        "description": "only findings for this watched brand (exact name as returned in `watching`) — omit for all of them"
      }
    }
  }

  arguments 14 lines copy
• research_ads unknown never probed

  Open-ended ad research that needs JUDGMENT across platforms — comparisons, "what angle is working", "who else is doing this", anything where the right sources are not known up front. It is an agentic loop (several rounds of library pulls plus a written synthesis) and typically takes 30-60 seconds, so it is the WRONG tool for a question that names its own answer. For one named brand’s live ads use pull_competitor_ads; for one keyword or one advertiser on Meta use search_meta_ads — both are a single call and return in a few seconds. Spends credits — an agentic loop, so a handful rather than the one-call cost of a targeted search.

  mcp-tool

  1234567891011121314151617181920212223242526

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "query"
    ],
    "properties": {
      "brand": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "object",
            "properties": {},
            "additionalProperties": {}
          }
        ],
        "description": "brand name or profile object to tailor the research to; omit to use the workspace’s saved brand"
      },
      "query": {
        "type": "string",
        "description": "what to research, e.g. \"the longest-running protein-pancake ads on Meta\""
      }
    }
  }

  arguments 26 lines copy
• search_meta_ads unknown never probed

  Structured Meta (Facebook/Instagram) Ad Library pull — use when you know exactly WHAT to fetch: a keyword (query) OR one advertiser (companyName / pageId). Returns compact JSON {page_name, body, cta, link, dates, media} per ad. For open-ended research that needs judgment across platforms, use research_ads instead. Spends a credit or two.

  mcp-tool

  12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "limit": {
        "type": "integer",
        "maximum": 9007199254740991,
        "minimum": -9007199254740991,
        "description": "max ads returned (1–25, default 8)"
      },
      "query": {
        "type": "string",
        "description": "keyword search across ALL advertisers (use INSTEAD of companyName/pageId)"
      },
      "pageId": {
        "type": "string",
        "description": "one advertiser’s ads by Facebook page id (most precise)"
      },
      "status": {
        "enum": [
          "ACTIVE",
          "INACTIVE",
          "ALL"
        ],
        "type": "string",
        "description": "ACTIVE = currently running; default ALL (includes proven past winners)"
      },
      "country": {
        "type": "string",
        "description": "2-letter code or 'ALL' (default ALL)"
      },
      "mediaType": {
        "enum": [
          "ALL",
          "IMAGE",
          "VIDEO",
          "MEME",
          "IMAGE_AND_MEME",
          "NONE"
        ],
        "type": "string",
        "description": "filter by creative type (default ALL)"
      },
      "companyName": {
        "type": "string",
        "description": "one advertiser’s ads by brand name"
      }
    }
  }

  arguments 49 lines copy
• search_google_ads unknown never probed

  Structured Google Ads Transparency pull for ONE advertiser (by domain or advertiserId) — use when you know the brand; use research_ads for open-ended research. Deliberately fetches the cheap BASIC listing (get_ad_details=false, ~1 credit — the detailed variant with per-ad headlines costs 25 credits/call and is not exposed here). Returns compact JSON {advertiser, format, adUrl, image, firstShown, lastShown} per ad.

  mcp-tool

  123456789101112131415161718192021222324

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "limit": {
        "type": "integer",
        "maximum": 9007199254740991,
        "minimum": -9007199254740991,
        "description": "max ads returned (1–25, default 8)"
      },
      "domain": {
        "type": "string",
        "description": "the advertiser's domain, e.g. nike.com"
      },
      "region": {
        "type": "string",
        "description": "2-letter region, default US"
      },
      "advertiserId": {
        "type": "string",
        "description": "Google advertiser id (AR…) when the domain is ambiguous"
      }
    }
  }

  arguments 24 lines copy
• search_linkedin_ads unknown never probed

  Structured LinkedIn Ad Library search by company name, keyword, or companyId — use for a targeted B2B pull; use research_ads for open-ended research. Returns compact JSON {advertiser, headline, description, cta, link, media, dates, impressions} per ad — LinkedIn is the one library exposing real impression counts. Spends about a credit.

  mcp-tool

  12345678910111213141516171819202122232425262728

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "limit": {
        "type": "integer",
        "maximum": 9007199254740991,
        "minimum": -9007199254740991,
        "description": "max ads returned (1–25, default 8)"
      },
      "company": {
        "type": "string",
        "description": "advertiser company name"
      },
      "keyword": {
        "type": "string",
        "description": "keyword across all advertisers"
      },
      "companyId": {
        "type": "string",
        "description": "LinkedIn company id (numeric) when the name is ambiguous"
      },
      "countries": {
        "type": "string",
        "description": "CSV of 2-letter codes like 'US,CA'; omit or 'ALL' = worldwide"
      }
    }
  }

  arguments 28 lines copy
• find_creators unknown never probed

  Scan organic TikTok, Instagram Reels and YouTube for a niche across a few query variants, fold the posts into creators, and rank them on median views, engagement rate and how often they show up for that niche; the top rows get follower counts AND public contact info (an Instagram business email / phone / category, the bio link, an email in a TikTok bio) so outreach can start from the result. Real people, not AI actors — for influencer sourcing, UGC casting and partnership prospecting ("who should we send product to?"). About one credit per search call (platforms × queries, default 3 × 3) plus one per enriched profile; repeats inside 20 minutes are free. Then shortlist (save_to_swipefile), check a profile (instagram_profile / fetch_social_data), draft outreach (generate_text), or approve them for Partnership Ads (manage_meta_partnership_creator).

  mcp-tool

  1234567891011121314151617181920212223242526272829303132333435363738394041424344

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "niche"
    ],
    "properties": {
      "limit": {
        "type": "number",
        "description": "creators to return, 1–30 (default 12)"
      },
      "niche": {
        "type": "string",
        "description": "product category, topic or hashtag — \"calorie tracker app\", \"matcha\", \"#cleanbeauty\""
      },
      "enrich": {
        "type": "boolean",
        "description": "read follower counts for the top 6 (default true, ~1 credit each)"
      },
      "queries": {
        "type": "number",
        "description": "query variants per platform, 1–4 (default 3); each is a paid search call"
      },
      "platforms": {
        "type": "array",
        "items": {
          "enum": [
            "tiktok",
            "instagram",
            "youtube"
          ],
          "type": "string"
        },
        "description": "default all three"
      },
      "minAvgViews": {
        "type": "number"
      },
      "minEngagement": {
        "type": "number",
        "description": "interactions per view, 0–1 (0.05 = 5%)"
      }
    }
  }

  arguments 44 lines copy
• search_posts unknown never probed

  The POSTS people make ABOUT a subject — a brand ("liquid death"), a product, a hobby ("coffee"), a hashtag ("#homecafe") — from whoever posted them, across organic TikTok, Instagram Reels and YouTube in ONE call, ranked by views. Not the brand's own ads (search_meta_ads / research_ads) and not the people (find_creators folds these same posts into creators): use it to see what is actually being posted and watched about a subject, to find clips worth cloning (clone_video), and to read the hooks and angles an audience already responds to. About one credit per platform searched (one query each by default; `queries` adds "best X" / "X review" / #tag variants, each a paid call); repeats inside 20 minutes are free.

  mcp-tool

  123456789101112131415161718192021222324252627282930313233

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "topic"
    ],
    "properties": {
      "limit": {
        "type": "number",
        "description": "posts per platform, 1–60 (default 24)"
      },
      "topic": {
        "type": "string",
        "description": "subject, brand, product or hashtag — \"liquid death\", \"coffee\", \"#homecafe\""
      },
      "queries": {
        "type": "number",
        "description": "query variants per platform, 1–4 (default 1); each is a paid search call"
      },
      "platforms": {
        "type": "array",
        "items": {
          "enum": [
            "tiktok",
            "instagram",
            "youtube"
          ],
          "type": "string"
        },
        "description": "default all three"
      }
    }
  }

  arguments 33 lines copy
• search_tiktok unknown never probed

  Organic TikTok keyword search (there is NO TikTok ad library) — top-performing videos to mine for hooks/trends/remixable creative. Returns compact JSON {desc, author, handle, plays, likes, link, cover} per video, ranked by plays. Use research_ads for open-ended research. Spends about a credit.

  mcp-tool

  12345678910111213141516171819

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "query"
    ],
    "properties": {
      "limit": {
        "type": "integer",
        "maximum": 9007199254740991,
        "minimum": -9007199254740991,
        "description": "max videos returned (1–25, default 8)"
      },
      "query": {
        "type": "string",
        "description": "keyword or hashtag (no # needed)"
      }
    }
  }

  arguments 19 lines copy
• search_instagram unknown never probed

  Organic Instagram REELS keyword search (/v2/instagram/reels/search — our only IG keyword surface; profile/hashtag pulls go through fetch_social_data with a handle). Returns compact JSON {desc, author, handle, plays, likes, link, cover} per reel, ranked by plays. Spends about a credit.

  mcp-tool

  12345678910111213141516171819

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "query"
    ],
    "properties": {
      "limit": {
        "type": "integer",
        "maximum": 9007199254740991,
        "minimum": -9007199254740991,
        "description": "max reels returned (1–25, default 8)"
      },
      "query": {
        "type": "string",
        "description": "keyword to search reels for"
      }
    }
  }

  arguments 19 lines copy
• search_youtube unknown never probed

  Organic YouTube keyword search (/v1/youtube/search) — videos to mine for hooks/angles/long-form structure. Returns compact JSON {desc (title), author, handle, plays, link, cover} per video, ranked by views. Spends about a credit.

  mcp-tool

  12345678910111213141516171819

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "query"
    ],
    "properties": {
      "limit": {
        "type": "integer",
        "maximum": 9007199254740991,
        "minimum": -9007199254740991,
        "description": "max videos returned (1–25, default 8)"
      },
      "query": {
        "type": "string",
        "description": "keyword to search videos for"
      }
    }
  }

  arguments 19 lines copy
• search_reddit unknown never probed

  Reddit keyword search (/v1/reddit/search, top-ranked) — a goldmine for the customer's OWN words (pain points, objections, language) to mine into ad hooks and copy. Returns compact JSON {desc (title+selftext), subreddit, upvotes, comments, link} per post. Spends about a credit.

  mcp-tool

  12345678910111213141516171819

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "query"
    ],
    "properties": {
      "limit": {
        "type": "integer",
        "maximum": 9007199254740991,
        "minimum": -9007199254740991,
        "description": "max posts returned (1–25, default 8)"
      },
      "query": {
        "type": "string",
        "description": "what to search Reddit for"
      }
    }
  }

  arguments 19 lines copy
• search_threads unknown never probed

  Organic Threads keyword search (/v1/threads/search) — short-form text/social posts for trend + voice research. Returns compact JSON {desc, author, handle, likes, link, cover} per post. Spends about a credit.

  mcp-tool

  12345678910111213141516171819

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "query"
    ],
    "properties": {
      "limit": {
        "type": "integer",
        "maximum": 9007199254740991,
        "minimum": -9007199254740991,
        "description": "max posts returned (1–25, default 8)"
      },
      "query": {
        "type": "string",
        "description": "keyword to search Threads for"
      }
    }
  }

  arguments 19 lines copy
• fetch_social_data unknown never probed

  Generic escape hatch for any ALLOWLISTED long-tail social/web endpoint the dedicated search_* tools don't cover — e.g. {path:'/v1/instagram/profile', params:{handle:'nike'}}. Allowlisted platform families: TikTok (+ TikTok Shop), Instagram, YouTube, Facebook (organic profiles/posts/events/marketplace), LinkedIn (organic posts/companies), Twitter/X, Reddit, Threads, Snapchat, Pinterest, Twitch, Bluesky, Truth Social, Rumble, Spotify, SoundCloud, GitHub, Google search, link-in-bio pages (Linktree etc.). Param names vary per endpoint (profiles use `handle`, keyword searches use `query`, Reddit uses `subreddit`). WARNING: returns RAW provider JSON — large and messy; prefer the dedicated search_* tools. Spends credits.

  mcp-tool

  12345678910111213141516171819

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "path"
    ],
    "properties": {
      "path": {
        "type": "string",
        "description": "exact endpoint path, e.g. '/v1/tiktok/profile' — non-allowlisted paths are rejected"
      },
      "params": {
        "type": "object",
        "properties": {},
        "description": "endpoint query params, e.g. {handle:'nike'}",
        "additionalProperties": {}
      }
    }
  }

  arguments 19 lines copy
• get_brand unknown never probed

  What Hermoso ALREADY KNOWS for this account/workspace — the same saved brand profile (products, logos, palette, positioning) + learned memory the web Studio uses. Call it when you need to know whether a brand is on file: if hasBrand is true you can omit brand everywhere; if false, onboard with draft_brand. Not a required first step before a render: the create tools read the saved brand by themselves. 0 credits.

  mcp-tool

  12345

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {}
  }

  arguments 5 lines copy
• draft_brand unknown never probed

  Onboard a brand profile — from a website domain, a free-text description, or a social handle — into a {name, products, logo, …} object you can pass to plan_ad / generate. 0 credits. IMPORTANT: a domain can resolve to a DIFFERENT company than intended (e.g. bala.com is an engineering firm, not the Bala fitness brand at shopbala.com). Before spending any credits on research or renders, VERIFY the returned `name` (and `summary`) match the brand the user meant; if it looks wrong, re-draft with the correct domain or a description (pass save:false until confirmed) — this tool cannot ask the user, so the caller owns that check.

  mcp-tool

  1234567891011121314151617181920212223242526

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "save": {
        "type": "boolean",
        "description": "save as the workspace’s brand (like Studio onboarding) so plan_ad/create use it automatically. Default: saves only when NO brand is saved yet; pass true to overwrite, false to never save"
      },
      "domain": {
        "type": "string",
        "description": "a website to scrape"
      },
      "platform": {
        "type": "string",
        "description": "platform for socialHandle (instagram/tiktok/…)"
      },
      "description": {
        "type": "string",
        "description": "a free-text brand description (no website)"
      },
      "socialHandle": {
        "type": "string",
        "description": "a social handle to draft from (influencers/creators) — pair with platform"
      }
    }
  }

  arguments 26 lines copy
• list_library unknown never probed

  Browse this workspace's Library — every image/video generated in the Studio, newest first (the same Library the web app shows). Returns served URLs you can open directly or hand to fetch_asset for a download link, plus each asset's kind, model, and age. Free, read-only.

  mcp-tool

  12345678910111213141516171819

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "kind": {
        "enum": [
          "image",
          "video",
          "all"
        ],
        "type": "string",
        "description": "filter by asset kind (default 'all')"
      },
      "limit": {
        "type": "number",
        "description": "max assets to return (default 20, max 60)"
      }
    }
  }

  arguments 19 lines copy
• fetch_asset unknown never probed

  Resolve a generated asset reference (a /generated/… path or any URL) to a clickable absolute URL + a direct download URL.

  mcp-tool

  1234567891011121314151617

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "url"
    ],
    "properties": {
      "url": {
        "type": "string",
        "description": "the asset url or /generated/ path"
      },
      "name": {
        "type": "string",
        "description": "optional filename for the download"
      }
    }
  }

  arguments 17 lines copy
• analyze_video unknown never probed

  Break a video ad down into its structure: the verbatim transcript (voiceover + on-screen text) with a beat list, plus duration and sampled frame timestamps. Use to study a reference/competitor ad before remixing its structure. Costs ~a transcription call.

  mcp-tool

  12345678910111213

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "url"
    ],
    "properties": {
      "url": {
        "type": "string",
        "description": "the video URL (a served /generated/ path or a public http(s) video)"
      }
    }
  }

  arguments 13 lines copy
• score_ad unknown never probed

  Virality/performance prediction for a finished ad (image or video URL): overall score, per-dimension breakdown (scroll-stop, hook, clarity, brand/product, CTA, retention, goal fit), strengths, and the single biggest fix. Use BEFORE spending on distribution, or to rank variants.

  mcp-tool

  12345678910111213141516171819202122232425

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "url"
    ],
    "properties": {
      "url": {
        "type": "string",
        "description": "the ad asset URL (a /generated/ path or public URL)"
      },
      "kind": {
        "enum": [
          "image",
          "video"
        ],
        "type": "string",
        "description": "'image' (default) or 'video'"
      },
      "intent": {
        "type": "string",
        "description": "what the ad is trying to achieve, for goal-fit scoring"
      }
    }
  }

  arguments 25 lines copy
• reframe_video unknown never probed

  Reframe a video to a different aspect ratio (e.g. 16:9 master → 9:16 vertical) with smart subject tracking. Paid render; returns the served URL of the reframed video.

  mcp-tool

  123456789101112131415161718192021222324252627

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "video",
      "aspectRatio"
    ],
    "properties": {
      "video": {
        "type": "string",
        "description": "the source video URL"
      },
      "aspectRatio": {
        "enum": [
          "9:16",
          "1:1",
          "16:9",
          "4:3",
          "3:4",
          "21:9",
          "9:21"
        ],
        "type": "string",
        "description": "the target aspect ratio"
      }
    }
  }

  arguments 27 lines copy
• upscale_video unknown never probed

  Upscale a video to higher resolution (2x) for final delivery. Paid render; returns the served URL. Two engines: the default ('standard') is the safe precision upscaler; engine:'flux' is the FLUX 3 video upscaler (1080p/2K/4K) with an optional mode:'creative' detail-enhancement pass — pick it when the user asks for the FLUX upscaler or wants added detail rather than a faithful enlargement.

  mcp-tool

  1234567891011121314151617181920212223242526272829

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "video"
    ],
    "properties": {
      "mode": {
        "enum": [
          "precise",
          "creative"
        ],
        "type": "string",
        "description": "FLUX only — 'creative' turns on its detail-enhancement pass; default precise"
      },
      "video": {
        "type": "string",
        "description": "the source video URL"
      },
      "engine": {
        "enum": [
          "standard",
          "flux"
        ],
        "type": "string",
        "description": "default 'standard', the precision upscaler. 'flux' = the FLUX 3 video upscaler"
      }
    }
  }

  arguments 29 lines copy
• edit_video unknown never probed

  EDIT/transform an existing video clip with a natural-language instruction (video-to-video) — KEEPS the original motion, timing and edit, changes the subject/setting/style. Use for 'change the background to a city', 'make it nighttime', 'restyle it as claymation', 'swap the product'. Best on 3–10s clips. NOT for mechanical cuts, trims, end cards or watermarks (use post_edit — seconds, ~2 credits, no AI model), NOT for making a new video (generate_video / render_ad), NOT for translating the spoken track (dub_video) and NOT for putting a saved creator's face on the motion (recast_motion). Paid render; returns the served URL of the edited clip.

  mcp-tool

  1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "video",
      "instruction"
    ],
    "properties": {
      "video": {
        "type": "string",
        "description": "the source video URL (from a previous render, a job result, or list_library)"
      },
      "elements": {
        "type": "array",
        "items": {
          "type": "object",
          "required": [
            "frontal"
          ],
          "properties": {
            "refs": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "up to 2 extra angles of the SAME subject"
            },
            "frontal": {
              "type": "string",
              "description": "the reference image URL"
            }
          },
          "additionalProperties": {}
        },
        "description": "OPTIONAL identity/product grounding (≤4): a creator portrait or the real product photo, so the edit restores the REAL thing instead of re-inventing it. Describe each one in the instruction. Leave out for a plain restyle"
      },
      "keepAudio": {
        "type": "boolean",
        "description": "default true — keep the source clip’s audio track. Set false to return the edit silent"
      },
      "instruction": {
        "type": "string",
        "description": "the exact transformation to apply, in the user’s own words"
      },
      "interactionId": {
        "type": "string",
        "description": "OPTIONAL: the interactionId an earlier Gemini Omni render or edit returned. The edit then continues that clip on the SAME Omni model from its own stored context (identity-true, no re-upload, usually cheaper). If that edit cannot run, the clip is edited by the video editor instead and the reply says so."
      }
    }
  }

  arguments 50 lines copy
• multiply_ad unknown never probed

  MULTIPLY a winning video ad into N variants: each gets a NEW character, outfit, location and/or objects while the cut, the camera motion, the pacing and the ORIGINAL AUDIO stay exactly as they were (that is what made the ad work), and any burned-in captions are removed. Pass the source video URL (a previous render, a job result, list_library, or the top performer from post_performance / meta_insights). HOW: the source video itself DRIVES each variant (motion transfer from one image-edited opening frame), so every variant comes back the SAME LENGTH as the source with the same cut, the same performance and the original audio — only the person, outfit, set and props change. Sources up to 30 seconds work as they are; longer ones are refused for free with the way out (trim it first: post_edit with ops [{op:'trim', start:0, end:30}] — clip_video is the AI highlight clipper, not a trim). Returns the plan and ONE JOB PER VARIANT — call get_job on each until it reports done; do not describe a variant before its URL arrives. Cost is quoted per variant in the reply (use dryRun:true to see the plan and the quote without rendering). Regions: pass regions:['Berlin','Tokyo'] to restyle variants per market; translation is a separate, explicit step — dub_video on a finished variant.

  mcp-tool

  123456789101112131415161718192021222324252627282930313233343536373839404142434445

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "video"
    ],
    "properties": {
      "axes": {
        "type": "array",
        "items": {
          "enum": [
            "character",
            "outfit",
            "location",
            "objects"
          ],
          "type": "string"
        },
        "description": "which axes to vary (default: all four)"
      },
      "count": {
        "type": "number",
        "description": "how many variants, 1-12 (default 6)"
      },
      "notes": {
        "type": "string",
        "description": "anything the variants must respect, e.g. \"keep it women 25-40\", \"no gyms\""
      },
      "video": {
        "type": "string",
        "description": "the source video URL"
      },
      "dryRun": {
        "type": "boolean",
        "description": "true = return the plan and the quote, render nothing"
      },
      "regions": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "markets to restyle for, one or more variants each, e.g. [\"Berlin\",\"Tokyo\",\"São Paulo\"] — visuals only; audio is never translated here"
      }
    }
  }

  arguments 45 lines copy
• hook_variants unknown never probed

  HOOK MULTIPLIER: give ONE finished video ad N NEW OPENING HOOKS and get N complete edited versions to A/B test. WHAT CHANGES: a new opening shot over roughly the first 1.5-4 seconds (the hook ends at the source's first shot cut in that range, else at 3s; hookSeconds overrides). WHAT STAYS: everything after that point is the original footage, and the ENTIRE original soundtrack (voiceover, music, sound) plays under every version unchanged, so every version is the SAME length, aspect ratio and resolution as the source. Because the audio is kept, each hook is a VISUAL hook built to play under the words the source already says there: nobody in it talks to camera, it carries no on-screen text, and it does NOT write a new spoken hook line. Every version uses a DIFFERENT named hook mechanic chosen for the product (open mid-problem, before/after snap, object into frame, satisfying macro, pattern interrupt, POV, whip/snap-zoom, unexpected place, countdown to reveal); list_hooks describes them. Pass the video's file URL (a previous render, a job result, list_library, or upload_file for a local file). 1-5 versions, default 3. REFUSED FOR FREE, before anything is billed: a source over 120 seconds (trim it with post_edit first), one too short to leave 2 seconds of the original after a 1.5 second hook, an unreadable file, or a link to a social post rather than a video file (use clone_video to remake someone else's ad). COST: a small planning read, then each version is billed like fix_beat for the hook's seconds; the reply quotes credits per version, and dryRun:true returns the plan and the quote without rendering (pass that `plan` back to render exactly those hooks without planning again). Returns ONE JOB PER VERSION; call get_job on each until it reports done, and never describe a version before its URL arrives. Uses the workspace brand's product photo as a reference in hooks that show the product (productImage overrides; useBrand:false sends none).

  mcp-tool

  12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "video"
    ],
    "properties": {
      "plan": {
        "description": "the `plan` object a previous dryRun returned, to render exactly those hooks without planning again"
      },
      "count": {
        "type": "number",
        "description": "how many hook versions, 1-5 (default 3)"
      },
      "notes": {
        "type": "string",
        "description": "anything the hooks must respect, e.g. \"keep it calm\", \"show the product in every hook\""
      },
      "video": {
        "type": "string",
        "description": "the finished video to give new hooks: its served file URL"
      },
      "dryRun": {
        "type": "boolean",
        "description": "true = return the plan and the quote, render nothing"
      },
      "useBrand": {
        "type": "boolean",
        "description": "false = send no brand name or product photo (for a video that is not this workspace brand’s)"
      },
      "resolution": {
        "enum": [
          "480p",
          "720p",
          "1080p"
        ],
        "type": "string",
        "description": "render tier for the new opening. Defaults to the source’s OWN tier so the hook matches the rest of the ad; a lower tier costs a lot less and is scaled into the source’s canvas (visibly softer for the first seconds). dryRun quotes whichever you pick."
      },
      "hookSeconds": {
        "type": "number",
        "description": "where the CURRENT hook ends, in seconds (1.5-4). Omit to use the first shot cut."
      },
      "productImage": {
        "type": "string",
        "description": "product photo URL used as a reference in hooks that show the product (defaults to the workspace brand’s first product photo)"
      }
    }
  }

  arguments 49 lines copy
• dub_video unknown never probed

  Localize a finished video into another language WITHOUT re-rendering it: the spoken track is transcribed, translated, re-voiced and lip-synced back onto the SAME footage, so the visuals, timing and edit are untouched. Just pass the video and the language — the script is read off the source automatically (pass `script` only to override what it heard). Paid; returns the served URL of the localized video.

  mcp-tool

  1234567891011121314151617181920212223242526

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "video",
      "language"
    ],
    "properties": {
      "video": {
        "type": "string",
        "description": "the source video URL"
      },
      "voice": {
        "type": "string",
        "description": "optional target voice preset, e.g. 'Aria' (warm female) or 'George' (confident male). Defaults to a voice matching the source speaker's register."
      },
      "script": {
        "type": "string",
        "description": "OPTIONAL override for the original spoken words. Leave this out — the source video is transcribed automatically. Only pass it when you already know the exact script and the auto-transcript got it wrong."
      },
      "language": {
        "type": "string",
        "description": "target language, e.g. 'Spanish', 'de', 'French (Canada)'"
      }
    }
  }

  arguments 26 lines copy
• change_voice unknown never probed

  Swap the narration of a finished video into a different voice — keeps the performance, lip-sync, and background sound. Use when the user likes the video but wants a different narrator voice; use dub_video only for language translation. Paid; returns the served URL.

  mcp-tool

  1234567891011121314151617

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "video"
    ],
    "properties": {
      "video": {
        "type": "string",
        "description": "the source video URL"
      },
      "voice": {
        "type": "string",
        "description": "target narrator voice preset name, e.g. 'Aria', 'George', 'Rachel', 'Sarah', 'Brian', 'Charlotte' (defaults to a warm female read). A saved VOICE CLONE of the user's own voice counts as a preset here — name it the way it is saved on their cast"
      }
    }
  }

  arguments 17 lines copy
• recast_motion unknown never probed

  Motion transfer: re-perform a reference video's motion with a different person/character (supply their image). The reference clip drives the movement; the image supplies the identity. Paid render, billed per output second (the output is as long as the reference clip, 3-30s); a 5s clip takes about 5 minutes. Runs on the Pro tier by default: 1080p, and the person really handles the object the reference performer handles.

  mcp-tool

  1234567891011121314151617181920212223242526272829303132333435363738

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "image",
      "video"
    ],
    "properties": {
      "tier": {
        "enum": [
          "pro",
          "standard"
        ],
        "type": "string",
        "description": "'pro' (default): 1080p and real hand-object interaction. 'standard': about 25% fewer credits and faster, but 720p, and it tends to mime a held object with empty hands. hermoso_capabilities lists the exact credits for both"
      },
      "image": {
        "type": "string",
        "description": "the actor/character image URL (who should appear)"
      },
      "video": {
        "type": "string",
        "description": "the reference video whose motion to re-perform"
      },
      "prompt": {
        "type": "string",
        "description": "optional scene/style guidance"
      },
      "orientation": {
        "enum": [
          "video",
          "image"
        ],
        "type": "string",
        "description": "which aspect to keep: the video's (default) or the image's"
      }
    }
  }

  arguments 38 lines copy
• plan_variations unknown never probed

  Fan a brief into N DISTINCT ad angles (different hooks/mechanics/audiences), each with its own headline + visual brief — then render each with generate_image and rank with score_ad. LLM planning only; renders nothing itself.

  mcp-tool

  123456789101112131415161718192021222324252627282930313233343536

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "product"
    ],
    "properties": {
      "brand": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "object",
            "properties": {},
            "additionalProperties": {}
          }
        ],
        "description": "brand name or profile object; OMIT to use the workspace’s saved brand"
      },
      "count": {
        "type": "integer",
        "maximum": 8,
        "minimum": 2,
        "description": "how many distinct variants (default 6)"
      },
      "product": {
        "type": "string",
        "description": "what to advertise"
      },
      "language": {
        "type": "string",
        "description": "output language for the variant copy (e.g. Spanish) — default English"
      }
    }
  }

  arguments 36 lines copy
• competitor_teardown unknown never probed

  Tear a competitor's ad strategy down into an actionable playbook: their opening-hook MIX, longest-running campaign THEMES, the WHITE SPACE nobody in their set runs, 2-3 render-ready COUNTER-PLAYS, and the territories they own that you should avoid. Pass `competitor` {name, domain?}. CONTRACT: supply `ads` (raw ad objects from a prior pull_competitor_ads / search_meta_ads call) to tear exactly those down, OR omit `ads` and this pulls the competitor's real Meta ads first (spends a credit or two, longest-running = proven winners). Auto-tailors the white space + counter-plays to YOUR saved brand. Spends credits (free when you pass ads).

  mcp-tool

  123456789101112131415161718192021222324252627282930313233343536373839

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "competitor"
    ],
    "properties": {
      "ads": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {},
          "additionalProperties": {}
        },
        "description": "ad objects to tear down (from pull_competitor_ads / search_meta_ads). Omit to auto-pull their Meta ads first."
      },
      "language": {
        "type": "string",
        "description": "output language (default English)"
      },
      "competitor": {
        "type": "object",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "the competitor brand name"
          },
          "domain": {
            "type": "string",
            "description": "their domain — sharpens the auto-pull page match"
          }
        },
        "description": "the competitor to tear down"
      }
    }
  }

  arguments 39 lines copy
• check_ad_policy unknown never probed

  Pre-flight ad copy against Meta's REAL, live Advertising Standards before you run it — a flat 1-credit check. Pulls Meta's actual policy pages and returns a verdict (pass / fix / block) where every flagged issue QUOTES Meta's own policy text verbatim plus a compliant rewrite that keeps the sell. It's a check, not an edit — it never changes the creative. Especially worth running for regulated-adjacent categories (health/supplements, weight-loss or beauty results claims, finance/crypto/insurance, alcohol, dating, gambling) or ANY strong/absolute/guaranteed claim.

  mcp-tool

  12345678910111213141516171819202122232425

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "copy"
    ],
    "properties": {
      "copy": {
        "type": "string",
        "description": "the ad copy / script / on-screen text to check"
      },
      "claims": {
        "type": "string",
        "description": "the claims / proof points the ad makes"
      },
      "category": {
        "type": "string",
        "description": "the product category — helps pick the relevant policy pages"
      },
      "imageDescription": {
        "type": "string",
        "description": "a description of the creative / image when relevant"
      }
    }
  }

  arguments 25 lines copy
• clone_static unknown never probed

  One-click STATIC-AD CLONE (the web app calls it Clone): rebuild a competitor/reference STATIC (image) ad as an on-brand version — SAME layout, composition and energy, but YOUR product, brand colours, logo and voice, with every trace of the source brand removed. Pass `imageUrl` = the static ad image to clone. Uses your saved brand (pass brandId to target a specific brand — that switches this key's active brand like use_brand). IMAGES ONLY — for a video ad use clone_video with its link, then render_ad. Bills as one image generation.

  mcp-tool

  1234567891011121314151617

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "imageUrl"
    ],
    "properties": {
      "brandId": {
        "type": "string",
        "description": "a brand id/name from list_brands to clone for; omit to use the active brand"
      },
      "imageUrl": {
        "type": "string",
        "description": "the URL of the static ad image to clone"
      }
    }
  }

  arguments 17 lines copy
• remix_static unknown never probed

  The OLD NAME of clone_static, kept so agents that already call it keep working. It is the same tool with the same inputs, result and cost; prefer clone_static.

  mcp-tool

  1234567891011121314151617

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "imageUrl"
    ],
    "properties": {
      "brandId": {
        "type": "string",
        "description": "a brand id/name from list_brands to clone for; omit to use the active brand"
      },
      "imageUrl": {
        "type": "string",
        "description": "the URL of the static ad image to clone"
      }
    }
  }

  arguments 17 lines copy
• mine_angles unknown never probed

  Mine ad ANGLES from real customer language: gathers the customer's own words (Reddit, TikTok, the brand's review page + review-site results) and returns a RANKED angle bank — each angle tagged (pain / outcome / identity / fear / competitive-displacement / social-proof / contrast), 2-5 VERBATIM proof quotes, a 0-100 score with breakdown, and a ready-to-run hook in the customer's own voice. Reads YOUR saved brand (pass brandId to target a specific brand — that switches this key's active brand like use_brand). To tear down a COMPETITOR use competitor_teardown instead. YOUR OWN REVIEWS: pass `reviews` (a list of review texts, or one pasted block: one per line, numbered, blank-line separated, or a CSV with a review column) and/or `reviewsUrl` (a CSV, TXT or JSON file from upload_file, or a review page; on a local CLI a file path works too). They are first-class evidence: every quote from them is checked word for word against what you sent and labelled 'your reviews', and a quote that is not verbatim is dropped and counted. useOwnReviewsOnly:true mines only your reviews and gathers nothing public. Limits: 300 reviews, 2,000 characters each, 40,000 in total; over that it is refused at no cost, so send fewer or split into batches. Each angle comes back with `next`: the exact plan_variations and generate_image arguments that turn it into finished statics (one generate_image per angle = statics with distinct angles). Spends a few credits.

  mcp-tool

  1234567891011121314151617181920212223242526272829303132

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "brandId": {
        "type": "string",
        "description": "a brand id/name from list_brands to mine for; omit to use the active brand"
      },
      "reviews": {
        "anyOf": [
          {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          {
            "type": "string"
          }
        ],
        "description": "your own customer reviews: a list of review texts, or one pasted block (one per line, numbered, blank-line separated, or CSV with a review column)"
      },
      "reviewsUrl": {
        "type": "string",
        "description": "a URL of your reviews: an uploaded CSV, TXT or JSON file (from upload_file) or a review page. On a local CLI a file path also works."
      },
      "useOwnReviewsOnly": {
        "type": "boolean",
        "description": "true = mine only your reviews, no public search (no search credits). Default false = merge with public customer language."
      }
    }
  }

  arguments 32 lines copy
• list_product_photos unknown never probed

  List the product photos ALREADY saved in your workspace — the brand's product library plus any app-store screens (also surfaces photos locked in your OTHER creations, since a set product lands in the shared library). FREE — returns each photo's url + label. Call it before set_product_image to see the existing photos you can reuse. Reads YOUR saved brand (pass brandId to target a specific brand — that switches this key's active brand like use_brand).

  mcp-tool

  12345678910

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "brandId": {
        "type": "string",
        "description": "a brand id/name from list_brands whose product library to list; omit to use the active brand"
      }
    }
  }

  arguments 10 lines copy
• set_product_image unknown never probed

  Lock an image as the ad's real PRODUCT photo and SAVE it as this brand's default product, so every later plan_ad / render_ad / generate_image grounds on the true packaging without being told again. Pass `imageUrl` = a product shot's URL — an image from a prior research result (an organic Instagram/TikTok post, a scraped page image), a workspace / list_product_photos url, or any public product photo. The server downloads it and runs a product+safety check: a lifestyle/scene shot with no clear product, or an off-category / unsafe image, is REJECTED and NOTHING is locked or saved (the summary says why). On PASS it persists the photo to a DURABLE url, writes it to the brand's product library as the DEFAULT, and READS THE BRAND BACK to confirm — `savedToBrand` and the summary report what the brand ACTUALLY holds now, never what was asked for, so if it did not become the default you are told instead of finding out from a paid render. Bills one vision check. Reads YOUR saved brand for the category match (pass brandId to target a specific brand — switches this key's active brand like use_brand).

  mcp-tool

  123456789101112131415161718192021

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "imageUrl"
    ],
    "properties": {
      "brandId": {
        "type": "string",
        "description": "a brand id/name from list_brands to lock the product for; omit to use the active brand"
      },
      "imageUrl": {
        "type": "string",
        "description": "the image URL to lock as the product (from a research result, a workspace / list_product_photos url, or any public product photo)"
      },
      "source_note": {
        "type": "string",
        "description": "a short note on where it came from, e.g. \"from their IG post\""
      }
    }
  }

  arguments 21 lines copy
• fetch_app_screens unknown never probed

  Pull an APP brand's REAL App Store screenshots into the workspace brand, so a screen-hungry native format can use them. Use when the brand has 0–1 app screens on file and you want make_template_ad(template:'app-ui-tour'), or the user asks to 'pull my app's screenshots'. Pass appName (defaults to the saved brand's name). FREE — a keyless App Store lookup. It needs a CONFIDENT match: an ambiguous or unknown app returns 0 screens and saves nothing, which you should relay plainly rather than retrying with guesses. On success the screens are saved to the brand (durable URLs) and are immediately usable.

  mcp-tool

  1234567891011121314

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "appName": {
        "type": "string",
        "description": "the app's name to look up on the App Store — defaults to the saved brand's name"
      },
      "brandId": {
        "type": "string",
        "description": "a brand id/name from list_brands to save the screens onto; omit to use the active brand"
      }
    }
  }

  arguments 14 lines copy
• list_meta_posts unknown never probed

  List the connected Facebook Page's or Instagram account's OWN existing posts — id, caption, permalink, publish date and format. THIS IS THE TOOL THAT GETS YOU THE postId every other Meta read needs: meta_post_insights, list_meta_comments and manage_meta_post all require one, and until now the only way to have a postId was to have just published it yourself with post_to_meta. Use it for "how did our last few posts do", to find a post the user describes loosely, or before backfill_posts. Pass target:'instagram' for the linked IG account (Stories are excluded — Meta's media edge does not return them); Facebook hides unpublished drafts unless you ask for them. Only ever reads a Page the brand has connected. Read-only, 0 credits.

  mcp-tool

  12345678910111213141516171819202122232425262728293031323334

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "limit": {
        "type": "number",
        "description": "how many posts (default 25, max 100)"
      },
      "cursor": {
        "type": "string",
        "description": "paging cursor returned by a previous call"
      },
      "pageId": {
        "type": "string",
        "description": "which connected Page — omit when the brand has only one"
      },
      "target": {
        "enum": [
          "facebook",
          "instagram"
        ],
        "type": "string",
        "description": "default facebook; 'instagram' reads the Page's linked IG business account"
      },
      "account": {
        "type": "string",
        "description": "which Instagram account — an @handle or id from list_connector_accounts(\"instagram\"). Needed when several are linked, and the way an Instagram Login (standalone) account is reached; omit for the one Page-linked account."
      },
      "includeUnpublished": {
        "type": "boolean",
        "description": "Facebook only — also return unpublished drafts (hidden by default)"
      }
    }
  }

  arguments 34 lines copy
• list_published_posts unknown never probed

  List every post Hermoso has recorded publishing for this brand — channel, permalink, caption, format, the HOOK and SUBJECT it was written to, and its measured engagement. This is the brand's own publishing history across all nine channels in one place, and it is the memory that makes 'which hook worked?' answerable at all. Each row says how it was recorded: 'captured' (written at publish time — the hook is what the author actually intended) or 'backfilled' (reconstructed from the platform afterwards, where the hook is only known if the post matched a Hermoso creation). A dash for engagement means the platform reported no number — that is NOT zero engagement. Read-only, 0 credits.

  mcp-tool

  1234567891011121314

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "limit": {
        "type": "number",
        "description": "max posts (default 50, max 200), newest first"
      },
      "channel": {
        "type": "string",
        "description": "filter to one channel: facebook, instagram, threads, x, linkedin, youtube, tiktok, reddit, pinterest, google_business"
      }
    }
  }

  arguments 14 lines copy
• list_hooks unknown never probed

  The curated menu of VISUAL scroll-stop HOOKS (how an ad opens) and SETTINGS (where it is staged) that plan_ad and render_ad accept, PLUS this brand's measured traction per hook. Call it before planning an ad to pick a hook deliberately instead of letting the model improvise one, and call it after publishing to see which ones are actually landing. Three things it will not do: it never recommends a hook from thin data — a verdict is SUPPRESSED below 5 measured posts and the reason is stated; it never compares across channels; and it reports hooks you have NEVER TRIED as a fact, not as advice, because 'you haven't tried this' is an observation and 'you should' would be a verdict drawn from zero data. A hook marked unusable in this brief says WHY (an on-screen-text hook cannot ride an authentic/UGC render, which carries zero on-screen text). Read-only, 0 credits.

  mcp-tool

  123456789101112131415161718192021222324252627

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "tier": {
        "enum": [
          "luxury",
          "premium",
          "drugstore"
        ],
        "type": "string",
        "description": "product tier, used with category — changes the FINISH of the room, never the room. Default premium."
      },
      "channel": {
        "type": "string",
        "description": "restrict the performance half to one channel (facebook, instagram, threads, x, linkedin, youtube, tiktok, reddit, pinterest)"
      },
      "category": {
        "type": "string",
        "description": "the product category (e.g. 'skincare serum', 'protein powder', 'sunglasses') — returns the setting our Location x Tier matrix puts that category in, with the reason"
      },
      "authentic": {
        "type": "boolean",
        "description": "true if the planned ad is an authentic/UGC/creator-register render — on-screen-text hooks are then reported unusable, with the reason"
      }
    }
  }

  arguments 27 lines copy
• post_performance unknown never probed

  Aggregate this brand's published posts to answer WHICH HOOKS AND SUBJECTS WORK. Groups by hook (default), subject, format (recipe), channel, media format or posting hour, reports the engagement RATE within each channel, and ranks the best and worst POSTS in each channel. Describe a post by the creative it carried (what it shows, its format, its link), not by its caption — the caption is the least important part of a post. THREE THINGS IT DELIBERATELY WILL NOT DO, and you should repeat them rather than paper over them: (1) it never sums metrics across channels — a LinkedIn impression and a TikTok view are different units, so every comparison is within one channel; (2) it SUPPRESSES a verdict below 5 measured posts and says so, because a confident recommendation from 3 posts is worse than none; (3) a post with no recorded hook (published outside Hermoso, or backfilled without a creation match) counts toward channel and format totals but never votes on which hook works. Present the `finding` verbatim if there is one, and the reason if there is not. Read-only, 0 credits.

  mcp-tool

  12345678910111213141516171819202122

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "axis": {
        "enum": [
          "hook",
          "subject",
          "recipe",
          "channel",
          "media",
          "hour"
        ],
        "type": "string",
        "description": "what to group by — default hook; recipe = the format of the creative"
      },
      "channel": {
        "type": "string",
        "description": "restrict to one channel"
      }
    }
  }

  arguments 22 lines copy
• diagnose_posts unknown never probed

  WHAT TO FIX NEXT, post by post — and the tool that fixes it. post_performance tells you which hook is AHEAD; this tells you what is WRONG with a given post and where the next edit goes. Under-distributed is A HOOK PROBLEM (change the opening: mine_angles, then list_hooks, then plan_variations). Seen but not held is A RETENTION PROBLEM (plan_variations to rebuild the middle against the same hook). Seen, held, and still not converting is AN OFFER PROBLEM. FOUR REFUSALS, AND YOU SHOULD REPEAT THEM RATHER THAN PAPER OVER THEM: (1) a post younger than ~24h is TOO EARLY and is never called a failure — it has not had its run; (2) a metric the platform does not publish is UNMEASURED, never zero — Facebook has published no post reach since 2026-06-15, Reddit publishes no impressions, and Google Business publishes nothing per-post at all; (3) below 5 measured posts on a channel there is no baseline of the brand's own, and the ONLY fallback is a published short-video hook floor that is NOT our measured number and does not transfer off TikTok/Instagram/YouTube — it is attributed in the output and you should attribute it too; (4) it does not always find a problem, and 'nothing here needs fixing' is a real answer rather than a failure to look. Hermoso cannot see conversions for an organic post — no channel reports installs or purchases against a post id — so the offer rung runs ONLY when the user tells you they are not converting and you pass converting:false. Print `summary` verbatim. Read-only, 0 credits.

  mcp-tool

  123456789101112131415161718

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "limit": {
        "type": "number",
        "description": "how many recent posts to diagnose (default 25, max 200). The baseline is always built from EVERY post recorded for the brand, never only these, so a bad month can never become its own definition of normal."
      },
      "channel": {
        "type": "string",
        "description": "restrict to one channel: facebook, instagram, threads, x, linkedin, youtube, tiktok, reddit, pinterest"
      },
      "converting": {
        "type": "boolean",
        "description": "pass false ONLY when the user has told you these posts are getting seen and are not converting — it re-reads the ones that are earning their reach as an offer problem instead of a win. Omit when you do not know; we cannot measure it."
      }
    }
  }

  arguments 18 lines copy
• collect_post_metrics unknown never probed

  Fetch fresh performance numbers for this brand's recorded posts and store them as a time-series. Metrics ACCRUE, so a post is read at ~24 hours and again at ~7 days; this collects whichever readings are due and skips the ones already taken. A channel that cannot report a metric records it as ABSENT with the reason — never as zero — and a read that fails is recorded as 'could not tell', which contributes to nothing. X IS SKIPPED BY DEFAULT because X bills us per API call: pass includeMetered:true to include it, and tell the user it costs credits BEFORE you do. The skip is always reported so a channel missing from the numbers is never mistaken for one that performed badly. Free except for X.

  mcp-tool

  123456789101112131415161718

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "properties": {
      "max": {
        "type": "number",
        "description": "cap how many posts to read in this run (default 40)"
      },
      "remeasure": {
        "type": "boolean",
        "description": "ALSO re-read posts older than 7 days whose every reading came back empty or failed — use after post_performance reports posts \"read but empty\", or once a channel's reader has been fixed. Otherwise those windows stay closed."
      },
      "includeMetered": {
        "type": "boolean",
        "description": "also read X, which BILLS CREDITS per post read — ask the user first"
      }
    }
  }

  arguments 18 lines copy
• backfill_posts unknown never probed

  Import this brand's PAST posts from a channel into the performance record, so 'which hook works' can draw on history rather than only on what was published since Hermoso started recording. Supports facebook, instagram, threads, youtube, tiktok, pinterest and bluesky; the others say plainly why they cannot (LinkedIn and Reddit have no enumerate-my-posts endpoint on our grant, X bills per read so it is excluded from bulk import, Google Business has had no per-post insights since 2023, and Telegram's Bot API cannot read a chat's past messages at all — nothing published before Hermoso is recoverable through a bot token). BOUNDED, RESUMABLE AND QUOTED: it runs as a DRY RUN by default and tells you how many posts it found and what reading them will cost — pass confirm:true to import, and pass the returned cursor to continue. AN IMPORTED POST IS WEAKER EVIDENCE THAN A RECORDED ONE and is labelled 'backfilled': its hook is recovered ONLY where the post matches a Hermoso creation by asset or caption. A post made outside Hermoso stays UNATTRIBUTED — it counts toward channel and format totals but never votes on which hook works. Never guess a hook from a caption. Free.

  mcp-tool

  1234567891011121314151617181920212223242526272829303132333435363738

  {
    "type": "object",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "required": [
      "channel"
    ],
    "properties": {
      "limit": {
        "type": "number",
        "description": "how many posts this page (default 50, max 200)"
      },
      "cursor": {
        "type": "string",
        "description": "resume from a previous run"
      },
      "channel": {
        "enum": [
          "facebook",
          "instagram",
          "threads",
          "youtube",
          "tiktok",
          "pinterest",
          "bluesky"
        ],
        "type": "string",
        "description": "which channel to import from"
      },
      "confirm": {
        "type": "boolean",
        "description": "actually import — omit for a dry run that only quotes the cost"
      },
      "accountRef": {
        "type": "string",
        "description": "which Page / account, when the brand has more than one"
      }
    }
  }

  arguments 38 lines copy