{"name":"io.github.hermoso-ai/hermoso","slug":"hermoso-ai-hermoso","title":"Hermoso","description":"841 tools, all usable alone: ad research, video ads, 10 publishing channels, 11 ad platforms.","url":"https://mcp.market/server/hermoso-ai-hermoso","grade":"B","score":83,"certified":false,"status":"active","category":"media","tags":["media"],"transport":"mixed","callable_via_gateway":true,"default_price_micros":0,"repository":"https://github.com/hermoso-ai/hermoso","website":"https://hermoso.ai/mcp/","version":"0.1.252","remotes":[{"type":"streamable-http","url":"https://app.hermoso.ai/mcp?src=registry"}],"packages":[{"registryType":"npm","registryBaseUrl":"https://registry.npmjs.org","identifier":"hermoso","version":"0.1.252","runtimeHint":"npx","transport":{"type":"stdio"},"packageArguments":[{"description":"Run the Hermoso stdio MCP server","value":"mcp","type":"positional"}],"environmentVariables":[{"description":"Hermoso agent key (hmk_…) from app.hermoso.ai → Settings → Agents & API. Required against the hosted app.","isSecret":true,"name":"HERMOSO_TOKEN"},{"description":"Hermoso API origin. Defaults to https://app.hermoso.ai; set http://localhost:3000 to run against your own server.","name":"HERMOSO_API_BASE"}]}],"tools":[{"name":"add_subtitles","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"video":{"type":"string","description":"the video to subtitle"},"textStyle":{"description":"the look: a preset or overrides; omit for the default","anyOf":[{"type":"string","enum":["pill","editorial","bold","minimal","handwritten","boxed"]},{"type":"object","properties":{"preset":{"type":"string","enum":["pill","editorial","bold","minimal","handwritten","boxed"]},"font":{"type":"string","enum":["sans","serif","elegant","condensed","hand"]},"weight":{"type":"number"},"size":{"anyOf":[{"type":"string","enum":["s","m","l","xl"]},{"type":"number"}]},"color":{"description":"#hex","type":"string"},"background":{"description":"none | pill | #hex box","type":"string"},"position":{"type":"string","enum":["top","center","lower","bottom"]},"textCase":{"type":"string","enum":["as-is","upper","lower","title"]},"italic":{"type":"boolean"},"outline":{"type":"boolean"},"shadow":{"type":"boolean"},"tilt":{"description":"degrees, ±12","type":"number"}}}]},"burn":{"description":"false = only the .srt","type":"boolean"}},"required":["video"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"analyze_video","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"url":{"type":"string","description":"the video URL (a served /generated/ path or a public http(s) video)"}},"required":["url"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"append_to_doc","description":"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).","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"documentId":{"type":"string","description":"the document id from create_doc"},"text":{"type":"string","description":"text to append at the end of the doc"}},"required":["documentId","text"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"append_to_sheet","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"spreadsheetId":{"type":"string","description":"the spreadsheet id from create_sheet"},"rows":{"type":"array","items":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}},"description":"rows to append — array of row arrays"},"range":{"description":"range to append at (default A1 / first sheet)","type":"string"}},"required":["spreadsheetId","rows"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"backfill_posts","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"channel":{"type":"string","enum":["facebook","instagram","threads","youtube","tiktok","pinterest","bluesky"],"description":"which channel to import from"},"confirm":{"description":"actually import — omit for a dry run that only quotes the cost","type":"boolean"},"limit":{"description":"how many posts this page (default 50, max 200)","type":"number"},"cursor":{"description":"resume from a previous run","type":"string"},"accountRef":{"description":"which Page / account, when the brand has more than one","type":"string"}},"required":["channel"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"billing_status","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"buy_credits","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"pack":{"description":"the pack id to buy (e.g. pack-2k) — omit to list the available packs first","type":"string"},"confirm":{"description":"set true to actually charge the saved card for `pack` (required for the one-click charge; ignored on the checkout-link path)","type":"boolean"},"quote_token":{"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","type":"string"}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"call_tool","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"name":{"type":"string","description":"the tool name exactly as find_tools returned it, e.g. create_meta_lead_form"},"args":{"description":"the tool's arguments as an object, exactly as its own schema takes them","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["name"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"cancel_scheduled","description":"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).","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"id":{"type":"string","description":"the scheduled post id from list_scheduled"},"brand":{"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.","type":"string"}},"required":["id"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"change_voice","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"video":{"type":"string","description":"the source video URL"},"voice":{"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","type":"string"}},"required":["video"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"check_ad_policy","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"copy":{"type":"string","description":"the ad copy / script / on-screen text to check"},"claims":{"description":"the claims / proof points the ad makes","type":"string"},"category":{"description":"the product category — helps pick the relevant policy pages","type":"string"},"imageDescription":{"description":"a description of the creative / image when relevant","type":"string"}},"required":["copy"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"clear_sheet_range","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"spreadsheetId":{"type":"string"},"sheetUrl":{"type":"string"},"range":{"type":"string","description":"the range to clear, e.g. \"A2:D50\" or \"Sheet1!A2:D50\""},"confirm":{"type":"boolean"},"confirmCells":{"description":"echo back the filled-cell count the unconfirmed call reported","type":"number"}},"required":["range"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"clip_video","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"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"},"count":{"description":"how many clips to cut, 1-8 (default 4)","type":"number"},"aspectRatio":{"description":"clip shape — '9:16' (default) vertical for Reels/Shorts/TikTok; 'keep' leaves the source framing untouched","type":"string","enum":["9:16","1:1","16:9","keep"]},"captions":{"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.","type":"boolean"}},"required":["video"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"clone_static","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"imageUrl":{"type":"string","description":"the URL of the static ad image to clone"},"brandId":{"description":"a brand id/name from list_brands to clone for; omit to use the active brand","type":"string"}},"required":["imageUrl"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"clone_video","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"url":{"type":"string","description":"the video to clone — a TikTok / Instagram Reel / Facebook / X / YouTube link, or a direct https video file URL"},"product":{"description":"what the new ad sells, plus any angle or offer; omit to use the saved brand's product","type":"string"},"changes":{"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\")","type":"string"},"brand":{"description":"brand name or profile object; OMIT to use the workspace's saved brand (see get_brand)","anyOf":[{"type":"string"},{"type":"object","properties":{},"additionalProperties":{}}]},"durationSeconds":{"description":"override the length in seconds; omit to match the original","type":"number"},"language":{"description":"language for the new ad's script and copy — default English","type":"string"}},"required":["url"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"collect_post_metrics","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"includeMetered":{"description":"also read X, which BILLS CREDITS per post read — ask the user first","type":"boolean"},"max":{"description":"cap how many posts to read in this run (default 40)","type":"number"},"remeasure":{"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.","type":"boolean"}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"competitor_teardown","description":"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).","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"competitor":{"type":"object","properties":{"name":{"type":"string","description":"the competitor brand name"},"domain":{"description":"their domain — sharpens the auto-pull page match","type":"string"}},"required":["name"],"description":"the competitor to tear down"},"ads":{"description":"ad objects to tear down (from pull_competitor_ads / search_meta_ads). Omit to auto-pull their Meta ads first.","type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"language":{"description":"output language (default English)","type":"string"}},"required":["competitor"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"connect_connector","description":"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*}.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"provider":{"type":"string","description":"the connector id: stripe, openai_ads, apple_ads, bluesky, telegram, bing_webmaster, posthog, mixpanel, amplitude, slack, discord, webhook"},"fields":{"description":"that provider's own field names and values, e.g. {\"apiKey\":\"…\"}; the names for each provider are in the description","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}}},"required":["provider"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"convert_onedrive_file","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"fileId":{"type":"string","description":"the OneDrive item id, from list_onedrive_files"},"format":{"description":"default pdf","type":"string","enum":["pdf","jpg"]},"width":{"description":"REQUIRED for jpg — output width in pixels","type":"number"},"height":{"description":"REQUIRED for jpg — output height in pixels","type":"number"}},"required":["fileId"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"create_brand","description":"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).","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"name":{"type":"string","description":"the brand / client name for the new workspace"},"activate":{"description":"switch this connection to the new brand (default true) — everything you do next scopes to it","type":"boolean"}},"required":["name"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"create_doc","description":"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).","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"title":{"description":"document title","type":"string"},"text":{"description":"body text to insert","type":"string"}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"create_drive_folder","description":"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).","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"name":{"type":"string","description":"folder name"},"parentId":{"description":"parent folder id for a nested folder (default: Drive root)","type":"string"}},"required":["name"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"create_onedrive_folder","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"name":{"type":"string","description":"folder name"},"parentId":{"description":"parent folder id for a nested folder (default: OneDrive root)","type":"string"}},"required":["name"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"create_sheet","description":"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).","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"title":{"description":"spreadsheet title","type":"string"},"rows":{"description":"rows to write — array of row arrays; first row = headers","type":"array","items":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}}}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"delete_brand","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"brand":{"type":"string","description":"brand id or exact name from list_brands"},"confirm":{"description":"REQUIRED true — this destroys the whole workspace and cannot be undone","type":"boolean"},"confirmName":{"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","type":"string"},"confirmConnectors":{"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","type":"number"}},"required":["brand"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"delete_creator","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"id":{"type":"string","description":"the creator id (from list_creators)"}},"required":["id"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"delete_drive_file","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"fileId":{"type":"string","description":"the Drive file id"},"permanent":{"description":"true = delete forever; default trashes (recoverable)","type":"boolean"},"confirm":{"description":"REQUIRED true","type":"boolean"}},"required":["fileId"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"delete_linkedin_lead_subscription","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"subscriptionId":{"type":"string"},"pageId":{"description":"the company Page that owns the form — from list_linkedin_pages; omit when one Page is shared","type":"string"},"adAccountId":{"description":"read forms owned by an AD ACCOUNT instead of a Page","type":"string"}},"required":["subscriptionId"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"delete_onedrive_file","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"fileId":{"type":"string","description":"the OneDrive item id"},"confirm":{"description":"REQUIRED true","type":"boolean"}},"required":["fileId"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"delete_playbook","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"id":{"type":"string","description":"the playbook id (from list_playbooks)"}},"required":["id"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"delete_skill","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"id":{"type":"string","description":"the custom skill id (from list_skills)"}},"required":["id"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"diagnose_posts","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"channel":{"description":"restrict to one channel: facebook, instagram, threads, x, linkedin, youtube, tiktok, reddit, pinterest","type":"string"},"limit":{"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.","type":"number"},"converting":{"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.","type":"boolean"}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"disconnect_connector","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"provider":{"type":"string","description":"provider id exactly as list_connectors reports it, e.g. \"meta\", \"google_ads\", \"youtube\", \"linkedin\""},"confirm":{"description":"REQUIRED true — reconnecting a sign-in account afterwards needs the user's browser; a paste-a-key account is reconnected with connect_connector","type":"boolean"},"account":{"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","type":"string"}},"required":["provider"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"draft_brand","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"domain":{"description":"a website to scrape","type":"string"},"description":{"description":"a free-text brand description (no website)","type":"string"},"socialHandle":{"description":"a social handle to draft from (influencers/creators) — pair with platform","type":"string"},"platform":{"description":"platform for socialHandle (instagram/tiktok/…)","type":"string"},"save":{"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","type":"boolean"}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"dub_video","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"video":{"type":"string","description":"the source video URL"},"language":{"type":"string","description":"target language, e.g. 'Spanish', 'de', 'French (Canada)'"},"script":{"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.","type":"string"},"voice":{"description":"optional target voice preset, e.g. 'Aria' (warm female) or 'George' (confident male). Defaults to a voice matching the source speaker's register.","type":"string"}},"required":["video","language"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"duplicate_scheduled","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"brand":{"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.","type":"string"},"id":{"type":"string","description":"the post to copy, from list_scheduled"},"at":{"description":"when the copy goes out — ISO timestamp or epoch milliseconds (default: an hour from now)","type":"string"},"useQueue":{"description":"instead of naming a time, take the brand’s next free posting slot","type":"boolean"},"timezone":{"description":"IANA zone for the queue, e.g. \"America/New_York\"","type":"string"},"channels":{"description":"post the copy to these channels instead of the original’s","type":"array","items":{"type":"string","enum":["facebook","instagram","threads","tiktok","youtube","linkedin","x","pinterest","google_business","bluesky","telegram"]}},"message":{"description":"a different caption for the copy","type":"string"},"captions":{"description":"per-channel caption overrides for the copy","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"imageUrl":{"type":"string"},"videoUrl":{"type":"string"},"imageUrls":{"description":"CAROUSEL — an ORDERED list of image URLs published as ONE swipeable post","type":"array","items":{"type":"string"}},"title":{"type":"string"},"link":{"type":"string"},"boardId":{"description":"PINTEREST — the board for the copy (list_pinterest_boards)","type":"string"},"chatId":{"description":"TELEGRAM — which chat, group or channel the copy goes to (@username or numeric id)","type":"string"},"linkedinOrganizationId":{"description":"LINKEDIN — publish the copy as this company Page (list_linkedin_pages)","type":"string"},"pageId":{"description":"FACEBOOK / INSTAGRAM / THREADS — which connected Page (list_meta_pages)","type":"string"},"locationId":{"description":"GOOGLE BUSINESS — which listing (list_business_locations)","type":"string"},"visibility":{"type":"string","enum":["public","unlisted","private","draft"]}},"required":["id"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"edit_video","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"video":{"type":"string","description":"the source video URL (from a previous render, a job result, or list_library)"},"instruction":{"type":"string","description":"the exact transformation to apply, in the user’s own words"},"keepAudio":{"description":"default true — keep the source clip’s audio track. Set false to return the edit silent","type":"boolean"},"elements":{"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","type":"array","items":{"type":"object","properties":{"frontal":{"type":"string","description":"the reference image URL"},"refs":{"description":"up to 2 extra angles of the SAME subject","type":"array","items":{"type":"string"}}},"required":["frontal"],"additionalProperties":{}}},"interactionId":{"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.","type":"string"}},"required":["video","instruction"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"enable_tools","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"groups":{"type":"array","items":{"type":"string"},"description":"Groups to switch on, e.g. ['ads']. Unknown names are refused by name rather than ignored."}},"required":["groups"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"error_detail","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"fingerprint":{"type":"string","description":"the `fp` value from list_errors"}},"required":["fingerprint"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"export_swipefile_deck","description":"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).","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"collection":{"description":"the swipefile collection to export, by name or id (default: the first collection)","type":"string"},"title":{"description":"deck title (default: the collection name)","type":"string"},"limit":{"description":"max ads to include, 1-60 (default 30)","type":"number"}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"fetch_app_screens","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"appName":{"description":"the app's name to look up on the App Store — defaults to the saved brand's name","type":"string"},"brandId":{"description":"a brand id/name from list_brands to save the screens onto; omit to use the active brand","type":"string"}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"fetch_asset","description":"Resolve a generated asset reference (a /generated/… path or any URL) to a clickable absolute URL + a direct download URL.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"url":{"type":"string","description":"the asset url or /generated/ path"},"name":{"description":"optional filename for the download","type":"string"}},"required":["url"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"fetch_social_data","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"path":{"type":"string","description":"exact endpoint path, e.g. '/v1/tiktok/profile' — non-allowlisted paths are rejected"},"params":{"description":"endpoint query params, e.g. {handle:'nike'}","type":"object","properties":{},"additionalProperties":{}}},"required":["path"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"find_competitors","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"domain":{"type":"string","description":"the brand domain, e.g. flourish.com"},"mode":{"description":"'competitors' (default, excludes the searched company), 'inspiration' (best relevant ads incl. it), or 'company'","type":"string","enum":["competitors","inspiration","company"]}},"required":["domain"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"find_creators","description":"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).","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"niche":{"type":"string","description":"product category, topic or hashtag — \"calorie tracker app\", \"matcha\", \"#cleanbeauty\""},"platforms":{"description":"default all three","type":"array","items":{"type":"string","enum":["tiktok","instagram","youtube"]}},"limit":{"description":"creators to return, 1–30 (default 12)","type":"number"},"queries":{"description":"query variants per platform, 1–4 (default 3); each is a paid search call","type":"number"},"minAvgViews":{"type":"number"},"minEngagement":{"description":"interactions per view, 0–1 (0.05 = 5%)","type":"number"},"enrich":{"description":"read follower counts for the top 6 (default true, ~1 credit each)","type":"boolean"}},"required":["niche"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"find_tools","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"query":{"description":"words from the task or the tool name, e.g. \"lead form\", \"whatsapp\", \"google ads keyword\", \"meta insights\"","type":"string"},"group":{"description":"limit to one group: core, research, create, channels, channel_admin, analytics, ads, files, workspace","type":"string"},"limit":{"description":"how many to return (default 12, max 40)","type":"number"},"onlyHealthy":{"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.","type":"boolean"}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"finish_video","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"videoUrl":{"type":"string","description":"the served URL of the video to finish (from a previous render/job)"},"header":{"description":"header pill copy, ≤40 chars (required when pills is on)","type":"string"},"sub":{"description":"accent sub-pill copy, ≤34 chars (usually the product/brand)","type":"string"},"points":{"description":"3-4 proof points, ≤44 chars each","type":"array","items":{"type":"string"}},"accent":{"description":"brand accent hex for the sub-pill","type":"string"},"pills":{"description":"default true — set false for a grain-only pass","type":"boolean"},"grain":{"description":"default false — anti-AI film-grain finish","type":"boolean"}},"required":["videoUrl"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"fix_beat","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"videoUrl":{"type":"string","description":"the served URL of the master video to fix"},"startSeconds":{"type":"number","description":"window start in seconds"},"endSeconds":{"type":"number","description":"window end in seconds (window 1.5-8s)"},"prompt":{"type":"string","description":"what the replacement footage should show — describe the shot, matching the master's style"},"refImage":{"description":"optional product/style anchor image URL","type":"string"},"speechWindows":{"description":"[[start,end],...] windows with spoken lines — the fix window must not overlap these","type":"array","items":{"type":"array","items":{"type":"number"}}}},"required":["videoUrl","startSeconds","endSeconds","prompt"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"forget","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"id":{"type":"string","description":"the memory item id (from list_memory)"}},"required":["id"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"format_sheet","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"spreadsheetId":{"type":"string"},"sheetUrl":{"type":"string"},"tab":{"description":"tab title or numeric sheetId (default: the first tab)","type":"string"},"boldHeader":{"type":"boolean"},"freezeRows":{"description":"how many top rows to freeze (default 1, 0 = none)","type":"number"},"autoResize":{"type":"boolean"}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"generate_avatar","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"image":{"type":"string","description":"local path or URL of the presenter portrait"},"script":{"type":"string","description":"the words the avatar speaks"},"voice":{"description":"voice name (Rachel/Sarah/George/Adam)","type":"string"},"resolution":{"description":"'1080p' (default) or '480p'/'720p' draft","type":"string"}},"required":["image","script"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"generate_image","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"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."},"refImages":{"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.","type":"array","items":{"type":"string"}},"useBrand":{"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","type":"boolean"},"raw":{"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.","type":"boolean"},"aspectRatio":{"description":"e.g. '1:1', '9:16', '16:9'","type":"string"},"model":{"description":"image model id from hermoso_capabilities","type":"string"},"imageSize":{"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","type":"string"}},"required":["prompt"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"generate_text","description":"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).","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"prompt":{"type":"string","description":"the writing task / question"},"raw":{"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.","type":"boolean"},"model":{"description":"a writing-model id from hermoso_capabilities (a Claude / Gemini / GPT / Llama / DeepSeek id) — omit for the default","type":"string"}},"required":["prompt"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"generate_video","description":"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).","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"prompt":{"type":"string","description":"the video prompt / shot description (for a refVideo edit, this is the transformation instruction)"},"raw":{"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.","type":"boolean"},"refImage":{"description":"local path or URL to anchor the first frame","type":"string"},"refVideo":{"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.","type":"string"},"endImage":{"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.","type":"string"},"loop":{"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.","type":"boolean"},"shots":{"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.","type":"array","items":{"type":"object","properties":{"prompt":{"type":"string","description":"what happens in this shot"},"seconds":{"type":"integer","minimum":1,"maximum":15,"description":"this shot’s length in whole seconds"}},"required":["prompt","seconds"]}},"extend":{"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).","type":"boolean"},"interactionId":{"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.","type":"string"},"durationSeconds":{"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).","type":"number"},"aspectRatio":{"description":"default '9:16'","type":"string"},"model":{"description":"video model id from hermoso_capabilities; a named model is never swapped without asking. Omit to let the router pick","type":"string"},"resolution":{"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.","type":"string","enum":["480p","720p","1080p","4k"]},"cameraMove":{"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.","type":"string","enum":["orbit","orbit_left","orbit_half","orbit_full","rise","crane_up","push_in","pull_back","reveal"]},"cameraTrajectory":{"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.","minItems":2,"maxItems":12,"type":"array","items":{"type":"object","properties":{"time":{"type":"number","minimum":0,"maximum":1,"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)"},"elevation":{"type":"number","minimum":-90,"maximum":90,"description":"vertical angle in degrees, -90 (below) to 90 (straight above)"},"distance":{"type":"number","exclusiveMinimum":0,"description":"distance from the subject in scene units, 1 = the distance of the still; smaller is closer"}},"required":["time","azimuth","elevation","distance"]}},"ttsScript":{"description":"voiceover script to speak","type":"string"},"ttsVoice":{"description":"voice name, e.g. Rachel / George","type":"string"},"musicMood":{"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.","type":"string"},"audio":{"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.","type":"boolean"}},"required":["prompt"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"generate_voice","description":"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).","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"text":{"type":"string","description":"the script to speak (≤900 characters)"},"engine":{"description":"voice-engine id: 'seed-audio' (default), 'eleven-v3', 'minimax-speech', or 'kokoro' — listed in hermoso_capabilities","type":"string"},"voice":{"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","type":"string"}},"required":["text"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"get_brand","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"get_drive_file","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"fileId":{"type":"string","description":"the Drive file id (from list_drive_files)"}},"required":["fileId"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"get_job","description":"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).","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"id":{"type":"string","description":"the job id, e.g. job_xxx"}},"required":["id"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"get_linkedin_lead","description":"One LinkedIn lead by id (from list_linkedin_leads), with every answer named by field. Personal data — show, never republish. Read-only, free.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"leadId":{"type":"string"},"pageId":{"description":"the company Page that owns the form — from list_linkedin_pages; omit when one Page is shared","type":"string"},"adAccountId":{"description":"read forms owned by an AD ACCOUNT instead of a Page","type":"string"}},"required":["leadId"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"get_onedrive_file","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"fileId":{"type":"string","description":"the OneDrive item id (from list_onedrive_files)"}},"required":["fileId"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"get_post_refill","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"get_settings","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"get_skill","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"name":{"type":"string","description":"bundle name from list_skills, e.g. hermoso-generate"}},"required":["name"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"hermoso_capabilities","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"hermoso_credits","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"import_from_cloud","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"provider":{"type":"string","enum":["drive","onedrive"],"description":"which cloud — `drive` is Google Drive, `onedrive` is Microsoft OneDrive"},"folderId":{"description":"the folder to import, from list_drive_files / list_onedrive_files (onlyFolders:true). Omit for the root of the drive.","type":"string"},"limit":{"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.","type":"number"}},"required":["provider"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"invite_member","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"email":{"type":"string","description":"the invitee’s email"},"role":{"description":"default member","type":"string","enum":["member","admin"]},"confirm":{"description":"REQUIRED true — this invites a real person","type":"boolean"}},"required":["email"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"leave_connector","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"provider":{"type":"string","description":"provider id exactly as list_connectors reports it, e.g. \"linkedin\", \"tiktok_ads\", \"meta\""}},"required":["provider"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"list_brands","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"list_business_locations","description":"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).","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"list_connector_accounts","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"provider":{"type":"string","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"],"description":"which connector’s accounts to list"}},"required":["provider"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"list_connectors","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"list_creators","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"limit":{"description":"max creators to return (default 24)","type":"number"}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"list_drive_files","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"query":{"description":"only files whose name contains this","type":"string"},"folderId":{"description":"list the contents of this folder id","type":"string"},"onlyFolders":{"description":"list folders only","type":"boolean"},"pageSize":{"description":"rows per page (1–200, default 50)","type":"number"},"pageToken":{"description":"cursor from a previous call","type":"string"},"includeTrashed":{"description":"include trashed files (default false)","type":"boolean"}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"list_errors","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"kind":{"description":"'ours' = a defect; 'user' = a refusal we authored; 'unknown' = we could not tell","type":"string","enum":["ours","user","unknown"]},"surface":{"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)","type":"string","enum":["http","mcp","agent","job","client"]},"since":{"description":"ISO timestamp — only groups last seen at or after this","type":"string"},"limit":{"description":"how many groups to return (default 50, max 200)","type":"number"}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"list_hooks","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"channel":{"description":"restrict the performance half to one channel (facebook, instagram, threads, x, linkedin, youtube, tiktok, reddit, pinterest)","type":"string"},"authentic":{"description":"true if the planned ad is an authentic/UGC/creator-register render — on-screen-text hooks are then reported unusable, with the reason","type":"boolean"},"category":{"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","type":"string"},"tier":{"description":"product tier, used with category — changes the FINISH of the room, never the room. Default premium.","type":"string","enum":["luxury","premium","drugstore"]}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"list_jobs","description":"List the most recent render jobs + how many are currently running, so you can report on or resume in-flight work.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"list_library","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"kind":{"description":"filter by asset kind (default 'all')","type":"string","enum":["image","video","all"]},"limit":{"description":"max assets to return (default 20, max 60)","type":"number"}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"list_linkedin_lead_events","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"limit":{"type":"number"}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"list_linkedin_lead_forms","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"pageId":{"description":"the company Page that owns the form — from list_linkedin_pages; omit when one Page is shared","type":"string"},"adAccountId":{"description":"read forms owned by an AD ACCOUNT instead of a Page","type":"string"}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"list_linkedin_lead_subscriptions","description":"The lead notification webhooks registered on a LinkedIn Page or ad account, with the id delete_linkedin_lead_subscription takes. Read-only, free.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"pageId":{"description":"the company Page that owns the form — from list_linkedin_pages; omit when one Page is shared","type":"string"},"adAccountId":{"description":"read forms owned by an AD ACCOUNT instead of a Page","type":"string"},"leadType":{"type":"string"}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"list_linkedin_leads","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"pageId":{"description":"the company Page that owns the form — from list_linkedin_pages; omit when one Page is shared","type":"string"},"adAccountId":{"description":"read forms owned by an AD ACCOUNT instead of a Page","type":"string"},"formId":{"description":"only this form (from list_linkedin_lead_forms)","type":"string"},"formVersion":{"description":"default 1","type":"number"},"since":{"description":"ISO date or epoch milliseconds","type":"string"},"until":{"type":"string"},"testLeadsOnly":{"description":"true returns ONLY test submissions","type":"boolean"},"leadType":{"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","type":"string","enum":["SPONSORED","COMPANY","EVENT","ORGANIZATION_PRODUCT"]},"limit":{"description":"per page, max 100","type":"number"},"start":{"description":"offset for the next page","type":"number"}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"list_linkedin_pages","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"list_memory","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"category":{"description":"filter to one bucket (Brand/Audience/Taste/Do/Don’t/Preference)","type":"string"},"limit":{"description":"max items (default 50, max 200)","type":"number"}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"list_meta_pages","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"list_meta_posts","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"target":{"description":"default facebook; 'instagram' reads the Page's linked IG business account","type":"string","enum":["facebook","instagram"]},"account":{"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.","type":"string"},"pageId":{"description":"which connected Page — omit when the brand has only one","type":"string"},"limit":{"description":"how many posts (default 25, max 100)","type":"number"},"cursor":{"description":"paging cursor returned by a previous call","type":"string"},"includeUnpublished":{"description":"Facebook only — also return unpublished drafts (hidden by default)","type":"boolean"}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"list_onedrive_files","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"query":{"description":"search — only items whose name matches this","type":"string"},"folderId":{"description":"list the contents of this folder id","type":"string"},"onlyFolders":{"description":"list folders only","type":"boolean"},"pageSize":{"description":"rows per page (1–200, default 50)","type":"number"},"pageToken":{"description":"cursor from a previous call","type":"string"}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"list_pinterest_boards","description":"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).","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"privacy":{"description":"filter by board privacy; default is everything the connection can see","type":"string","enum":["ALL","PUBLIC","PROTECTED","SECRET"]}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"list_playbooks","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"limit":{"description":"max playbooks to return (default 25, max 100)","type":"number"},"full":{"description":"true to return every hook/angle/play in the text, not just the headline counts","type":"boolean"}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"list_product_photos","description":"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).","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"brandId":{"description":"a brand id/name from list_brands whose product library to list; omit to use the active brand","type":"string"}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"list_published_posts","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"channel":{"description":"filter to one channel: facebook, instagram, threads, x, linkedin, youtube, tiktok, reddit, pinterest, google_business","type":"string"},"limit":{"description":"max posts (default 50, max 200), newest first","type":"number"}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"list_scheduled","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"brand":{"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.","type":"string"},"id":{"description":"one post id from this list: returns that post in full, every caption and setting included","type":"string"},"channel":{"description":"only posts that include this channel, e.g. \"pinterest\" or \"x\"","type":"string"},"upcoming":{"description":"how many queued posts to list, soonest first (default 25, max 200)","type":"number"},"fired":{"description":"how many already-fired posts to list, most recent last (default 15, max 200)","type":"number"}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"list_sheet_tabs","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"spreadsheetId":{"description":"the spreadsheet id (from create_sheet, or list_drive_files for one the user picked)","type":"string"},"sheetUrl":{"description":"a Google Sheets URL — the id is extracted from it","type":"string"}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"list_skills","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"list_swipefile","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"collection":{"description":"only list ads in this collection (by name or id) — omit for every collection","type":"string"},"limit":{"description":"max ads to return (default 50, max 500)","type":"number"}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"list_team","description":"List the members of the current brand workspace — email, role (admin/member) and status. Read-only, free.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"list_telegram_chats","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"limit":{"description":"how many recent updates to scan, 1–100 (default 100)","type":"number"}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"list_watch_findings","description":"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).","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"competitor":{"description":"only findings for this watched brand (exact name as returned in `watching`) — omit for all of them","type":"string"},"limit":{"description":"max findings to return (default 25, max 75 — the server keeps at most 75, and at most 15 per brand)","type":"number"}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"list_whatsapp_accounts","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"make_explainer","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"topic":{"type":"string","description":"what the explainer should teach or explain — a topic or a short brief"},"durationSeconds":{"description":"target length 20-120s (default 60); drives the section count — ~10s of narration each, 3-8 sections","type":"number"},"frameDensity":{"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.","type":"string","enum":["standard","lean","minimal"]},"aspectRatio":{"description":"'9:16' default","type":"string","enum":["9:16","16:9","1:1","4:5","3:4"]},"style":{"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).","type":"string","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"]},"channel":{"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'.","type":"string","enum":["explainer","history","kids","fairytale"]},"voice":{"description":"narration voice name — omit for the default warm read","type":"string"},"captions":{"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.","type":"boolean"},"subtitles":{"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.","type":"boolean"},"music":{"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.","type":"string"},"upscale":{"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.","type":"number"},"endCard":{"description":"append the branded end card. DEFAULT FALSE — set true ONLY when the user asks for one","type":"boolean"},"brandName":{"description":"brand name for the end card — omit to leave it unbranded","type":"string"}},"required":["topic"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"make_template_ad","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"config":{"type":"object","properties":{},"additionalProperties":{},"description":"the template config — MUST include config.template (one of the template ids above) plus that template's fields"}},"required":["config"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"make_thumbnail","description":"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.\n\nCONCEPT — 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.\n\nTHREE GATES, all BEFORE you render:\n1. 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.\n2. 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.\n3. 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.\n\nIDENTITY 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.\n\nPROMPT 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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"framework":{"description":"concept framework id (default 'posed_portrait'); see the list in this description / hermoso_capabilities","type":"string"},"frameworkRequested":{"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","type":"boolean"},"sceneBrief":{"description":"what the thumbnail depicts — the concept in one dense sentence, rendered exactly","type":"string"},"topic":{"description":"the video's topic — used to pick the hero object when you don't name keyElements","type":"string"},"headline":{"description":"2–4 word headline. Typeset OVER the finished render by default (free, always legible); newlines split it into stacked lines","type":"string"},"headlineLines":{"description":"explicit headline lines (up to 3) — overrides splitting `headline` on newlines","type":"array","items":{"type":"string"}},"bakeText":{"description":"default false. true paints the headline INTO the generation — only on an explicit user ask; it leaks garbled text elsewhere in the frame","type":"boolean"},"bakedUiText":{"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","type":"string"},"overlayStyle":{"description":"headline style: 'beast' (default, white + heavy black stroke) / 'fire' / 'neon-lime' / 'clean-glass' / 'marker'","type":"string"},"font":{"description":"headline font (default Anton). Alternatives incl. Bebas Neue, Oswald, Archivo Black, Montserrat, Inter, Playfair Display","type":"string"},"headlinePlace":{"description":"where the headline sits — never over the face (default 'bottom')","type":"string","enum":["bottom","top","center"]},"faceImages":{"description":"up to 3 face photos (URLs or local paths) — each becomes a locked CHARACTER identity, in order","type":"array","items":{"type":"string"}},"people":{"description":"people described in prose instead of by photo (each still gets the chosen expression)","type":"array","items":{"type":"object","properties":{"describe":{"type":"string"}},"required":["describe"],"additionalProperties":{}}},"castGenericPerson":{"description":"pass true only after the user has explicitly chosen a generated stranger over their own face","type":"boolean"},"emotion":{"description":"the expression on the face (default 'shock') — a preset id or your own phrase","type":"string"},"emotions":{"description":"render one variant per emotion (variants = emotions × takes, max 16)","type":"array","items":{"type":"string"}},"takes":{"description":"camera takes per emotion, 1–4: designed framing / low-angle hero / extreme close-up / wide dutch tilt","type":"number"},"variants":{"description":"how many thumbnails to render (default 1, max 16). Each is its own billed render — offer a set of 4 rather than assuming","type":"number"},"aspectRatio":{"description":"'16:9' (YouTube, default) / '9:16' (Shorts) / '4:5' (Instagram) / '4:3' / '1:1'","type":"string"},"keyElements":{"description":"signature props / effects that make it pop — oversized, flying toward camera","type":"string"},"location":{"description":"place, time of day, weather, atmosphere","type":"string"},"composition":{"description":"override the default large-foreground-subject composition","type":"string"},"background":{"description":"override the default bold saturated colour-field background","type":"string"},"rimColor":{"description":"colored back+hair light — ONLY when the user names one: 'ice-blue' / 'neon-magenta' / 'toxic-lime' / 'amber-gold' / 'pure-white'","type":"string"},"restrainedGrade":{"description":"true for a calm / premium / muted look instead of the default punchy poster grade","type":"boolean"},"logo":{"description":"a brand logo URL or path to place into the composition","type":"string"},"logo3d":{"description":"first turn the flat logo into a volumetric 3D render (one extra billed image), then composite that","type":"boolean"},"split":{"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","type":"object","properties":{"mode":{"type":"string","enum":["plain","before_after","versus","custom"]},"panels":{"type":"array","items":{"type":"string"}}},"required":["mode"],"additionalProperties":{}},"reference":{"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","type":"object","properties":{},"additionalProperties":{}},"tweak":{"type":"object","properties":{"kind":{"type":"string","enum":["emotion","background","background_color","rim_light"]},"value":{"type":"string"}},"required":["kind","value"],"description":"surgical pixel-faithful edit of a FINISHED thumbnail — needs sourceImage"},"sourceImage":{"description":"the finished thumbnail URL a `tweak` edits; tweaks chain, so feed each accepted output into the next","type":"string"},"forceGenerate":{"description":"render the 'screenshot' framework anyway (it is normally a real video frame, not a generation)","type":"boolean"}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"manage_sheet_tabs","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"spreadsheetId":{"type":"string"},"sheetUrl":{"type":"string"},"action":{"type":"string","enum":["add","rename","delete"]},"tab":{"description":"which tab — its title or numeric sheetId (rename / delete)","type":"string"},"title":{"description":"the name for the new tab (action:\"add\")","type":"string"},"newTitle":{"description":"what to rename the tab to (action:\"rename\")","type":"string"},"confirm":{"type":"boolean"},"confirmCells":{"type":"number"}},"required":["action"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"mine_angles","description":"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. Spends a few credits.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"brandId":{"description":"a brand id/name from list_brands to mine for; omit to use the active brand","type":"string"}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"multiply_ad","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"video":{"type":"string","description":"the source video URL"},"count":{"description":"how many variants, 1-12 (default 6)","type":"number"},"axes":{"description":"which axes to vary (default: all four)","type":"array","items":{"type":"string","enum":["character","outfit","location","objects"]}},"notes":{"description":"anything the variants must respect, e.g. \"keep it women 25-40\", \"no gyms\"","type":"string"},"regions":{"description":"markets to restyle for, one or more variants each, e.g. [\"Berlin\",\"Tokyo\",\"São Paulo\"] — visuals only; audio is never translated here","type":"array","items":{"type":"string"}},"dryRun":{"description":"true = return the plan and the quote, render nothing","type":"boolean"}},"required":["video"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"plan_ad","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"brand":{"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","anyOf":[{"type":"string"},{"type":"object","properties":{},"additionalProperties":{}}]},"product":{"type":"string","description":"what to advertise + any angle/offer the user specified"},"format":{"description":"'image', 'video', or 'auto' when unspecified","type":"string","enum":["auto","image","video"]},"durationSeconds":{"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.","type":"number"},"hook":{"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.","type":"string"},"setting":{"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.","type":"string"},"recipe":{"description":"a recipe id from hermoso_capabilities to force an archetype","type":"string"},"reference":{"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","type":"string"},"language":{"description":"output language for the ad copy (e.g. Spanish) — default English","type":"string"}},"required":["product"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"plan_variations","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"brand":{"description":"brand name or profile object; OMIT to use the workspace’s saved brand","anyOf":[{"type":"string"},{"type":"object","properties":{},"additionalProperties":{}}]},"product":{"type":"string","description":"what to advertise"},"count":{"description":"how many distinct variants (default 6)","type":"integer","minimum":2,"maximum":8},"language":{"description":"output language for the variant copy (e.g. Spanish) — default English","type":"string"}},"required":["product"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"post_edit","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"videoUrl":{"type":"string","description":"the served URL of the video to edit"},"ops":{"type":"array","items":{"type":"object","properties":{"op":{"type":"string","enum":["trim","speed","mute","audio_gain","fade_out","append_card","watermark","grain"]},"start":{"description":"trim/mute window start (s)","type":"number"},"end":{"description":"trim/mute window end (s)","type":"number"},"factor":{"description":"speed 0.5-2","type":"number"},"db":{"description":"audio_gain -20..+6 dB","type":"number"},"seconds":{"description":"fade_out 0.3-3s / append_card 2-5s","type":"number"},"headline":{"description":"append_card: big line (defaults to the brand name)","type":"string"},"tagline":{"description":"append_card: smaller line under the headline","type":"string"},"sub":{"description":"append_card: the pill line (defaults to the brand website)","type":"string"},"background":{"description":"append_card: card background — hex or a color name ('red', 'navy'…); the user's stated color always wins over the brand palette","type":"string"},"card_html":{"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","type":"string"},"corner":{"description":"watermark corner (default br)","type":"string","enum":["tl","tr","bl","br"]},"intensity":{"description":"grain look","type":"string","enum":["default","strong"]}},"required":["op"]},"description":"the ordered edit plan (max 6 ops)"},"brandName":{"description":"override the workspace brand name","type":"string"},"domain":{"description":"override the brand website","type":"string"},"accent":{"description":"override the brand accent hex","type":"string"}},"required":["videoUrl","ops"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"post_performance","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"axis":{"description":"what to group by — default hook; recipe = the format of the creative","type":"string","enum":["hook","subject","recipe","channel","media","hour"]},"channel":{"description":"restrict to one channel","type":"string"}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"post_to_bluesky","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"account":{"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.","type":"string"},"text":{"type":"string","description":"The post, up to 300 characters / 3000 UTF-8 bytes."},"imageUrls":{"description":"Up to 4 public image URLs to attach. Cannot be combined with videoUrl.","type":"array","items":{"type":"string"}},"altText":{"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.","anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"videoUrl":{"description":"One public MP4 URL. Cannot be combined with imageUrls. Bluesky transcodes it, which takes a minute or two.","type":"string"},"videoAlt":{"description":"Alt text describing the video, for accessibility.","type":"string"},"captions":{"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.","type":"array","items":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"langs":{"description":"BCP-47 language tags, e.g. ['en'].","type":"array","items":{"type":"string"}},"linkCard":{"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.","anyOf":[{"type":"boolean"},{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}]}},"required":["text"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"post_to_google_business","description":"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).","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"brand":{"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.","type":"string"},"hook":{"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.","type":"string"},"subject":{"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.","type":"string"},"summary":{"description":"the body text of the Post","type":"string"},"locationId":{"description":"which listing, e.g. 'locations/123' from list_business_locations — only needed when the account manages more than one","type":"string"},"imageUrl":{"description":"a Hermoso render image URL (or an upload_file url) to show on the Post","type":"string"},"topicType":{"description":"default STANDARD","type":"string","enum":["STANDARD","EVENT","OFFER","ALERT"]},"actionType":{"description":"the button on the Post","type":"string","enum":["BOOK","ORDER","SHOP","LEARN_MORE","SIGN_UP","CALL"]},"link":{"description":"the URL the button opens — not for CALL, and ignored on an OFFER","type":"string"},"title":{"description":"headline — REQUIRED for EVENT and OFFER","type":"string"},"startDate":{"description":"YYYY-MM-DD — REQUIRED for EVENT and OFFER","type":"string"},"endDate":{"description":"YYYY-MM-DD, defaults to startDate","type":"string"},"couponCode":{"description":"OFFER only","type":"string"},"redeemOnlineUrl":{"description":"OFFER only — this is the link Google actually uses on an offer","type":"string"},"termsConditions":{"description":"OFFER only","type":"string"},"languageCode":{"description":"BCP-47 language of the Post, default 'en'","type":"string"}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"post_to_linkedin","description":"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).","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"brand":{"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.","type":"string"},"hook":{"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.","type":"string"},"subject":{"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.","type":"string"},"text":{"type":"string","description":"the post text"},"imageUrl":{"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).","type":"string"},"imageUrls":{"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.","type":"array","items":{"type":"string"}},"idempotencyKey":{"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.","type":"string"},"allowDuplicate":{"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.","type":"boolean"},"visibility":{"description":"default PUBLIC","type":"string","enum":["PUBLIC","CONNECTIONS"]}},"required":["text"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"post_to_linkedin_page","description":"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).","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"brand":{"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.","type":"string"},"hook":{"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.","type":"string"},"subject":{"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.","type":"string"},"organizationId":{"description":"numeric Page id from list_linkedin_pages","type":"string"},"text":{"type":"string","description":"the post text"},"linkUrl":{"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.","type":"string"},"linkTitle":{"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.","type":"string"},"linkDescription":{"description":"the sub-line on the preview card. Same rule as linkTitle: absent means blank, because LinkedIn will not fetch it.","type":"string"},"linkThumbnailUrl":{"description":"a Hermoso-hosted image used as the card’s picture (uploaded to LinkedIn for you). Without it the card has no image.","type":"string"},"imageUrl":{"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.","type":"string"},"videoUrl":{"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.","type":"string"},"imageUrls":{"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.","type":"array","items":{"type":"string"}},"idempotencyKey":{"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.","type":"string"},"allowDuplicate":{"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.","type":"boolean"},"altText":{"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.","anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"title":{"description":"video title","type":"string"},"captionsSrt":{"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.","type":"string"},"videoThumbnailUrl":{"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.","type":"string"},"visibility":{"description":"default PUBLIC","type":"string","enum":["PUBLIC","CONNECTIONS"]},"targetAudience":{"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.","type":"object","properties":{"geoLocations":{"type":"array","items":{"type":"string"}},"industries":{"type":"array","items":{"type":"string"}},"seniorities":{"type":"array","items":{"type":"string"}},"jobFunctions":{"type":"array","items":{"type":"string"}},"staffCountRanges":{"type":"array","items":{"type":"string","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"]}},"degrees":{"type":"array","items":{"type":"string"}},"fieldsOfStudy":{"type":"array","items":{"type":"string"}},"organizations":{"type":"array","items":{"type":"string"}}}}},"required":["text"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"post_to_meta","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"brand":{"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.","type":"string"},"hook":{"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.","type":"string"},"subject":{"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.","type":"string"},"message":{"description":"post text / caption","type":"string"},"imageUrl":{"description":"public https URL, a data: URI, or a Hermoso /generated path (upload_file gives you one for a local file)","type":"string"},"videoUrl":{"description":"public https URL, data: URI, or /generated path — FB video post / IG Reel","type":"string"},"productTags":{"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.","type":"array","items":{}},"imageUrls":{"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.","type":"array","items":{"type":"string"}},"idempotencyKey":{"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.","type":"string"},"allowDuplicate":{"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.","type":"boolean"},"async":{"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.","type":"boolean"},"link":{"description":"a URL to attach (FB text post only)","type":"string"},"collaborators":{"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.","type":"array","items":{"type":"string"}},"target":{"description":"default facebook; instagram → the Page’s linked IG; threads → the brand’s connected Threads account","type":"string","enum":["facebook","instagram","threads"]},"account":{"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.","type":"string"},"scheduleAt":{"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.","type":"string"},"locationId":{"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.","type":"string"},"audience":{"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.","type":"object","properties":{"countries":{"description":"two-letter codes, e.g. [\"CA\",\"US\"]","type":"array","items":{"type":"string"}},"regions":{"description":"Meta location keys for regions/states","type":"array","items":{"type":"string"}},"cities":{"description":"Meta location keys for cities","type":"array","items":{"type":"string"}},"minAge":{"anyOf":[{"type":"number","const":13},{"type":"number","const":15},{"type":"number","const":18},{"type":"number","const":21},{"type":"number","const":25}]}}},"place":{"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.","type":"string"},"callToAction":{"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.","type":"string","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"]},"callToActionLink":{"description":"FACEBOOK — where the button goes, when that is not the post’s own `link`.","type":"string"},"linkName":{"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.","type":"string"},"linkDescription":{"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.","type":"string"},"linkPicture":{"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.","type":"string"},"coverUrl":{"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.","type":"string"},"thumbOffset":{"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.","type":"number"},"shareToFeed":{"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.","type":"boolean"},"audioName":{"description":"INSTAGRAM REEL — the name of the Reel’s audio track, which is what viewers tap through to. REELS ONLY.","type":"string"},"paidPartnership":{"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.","type":"boolean"},"brandedContentSponsorIds":{"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.","type":"array","items":{"type":"string"}},"trialReel":{"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.","type":"string","enum":["MANUAL","SS_PERFORMANCE"]},"story":{"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.","type":"boolean"},"aiGenerated":{"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.","type":"boolean"},"altText":{"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.)","anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"pageId":{"description":"target Page id (from list_meta_pages); omit = first Page","type":"string"},"linkAttachment":{"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.","type":"string"},"replyControl":{"description":"THREADS ONLY — who may reply. Default is everyone.","type":"string","enum":["everyone","accounts_you_follow","mentioned_only","parent_post_author_only","followers_only"]},"quotePostId":{"description":"THREADS ONLY — the id of a post to QUOTE. A quote post is a distinct post type, not a formatting option.","type":"string"},"topicTag":{"description":"THREADS ONLY — one topic tag for discovery, 1–50 characters. A leading # is stripped for you; Threads refuses \".\" and \"&\".","type":"string"},"countryCodes":{"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.","type":"array","items":{"type":"string"}},"crossreshareToIg":{"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.","type":"boolean"},"crossreshareDarkMode":{"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.","type":"boolean"}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"post_to_pinterest","description":"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).","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"account":{"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.","type":"string"},"brand":{"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.","type":"string"},"hook":{"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.","type":"string"},"subject":{"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.","type":"string"},"boardId":{"type":"string","description":"numeric board id from list_pinterest_boards — the user picks it, never guess"},"imageUrl":{"description":"a Hermoso render image URL (or an upload_file url)","type":"string"},"videoUrl":{"description":"a Hermoso render video URL — takes 1–2 minutes to ingest","type":"string"},"imageUrls":{"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.","type":"array","items":{"type":"string"}},"idempotencyKey":{"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.","type":"string"},"allowDuplicate":{"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.","type":"boolean"},"title":{"description":"Pin title, max 100 characters","type":"string"},"description":{"description":"Pin description, max 800 characters — this is what Pinterest search reads","type":"string"},"link":{"description":"destination URL the Pin clicks through to","type":"string"},"altText":{"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.","anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"slideText":{"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.","type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"link":{"type":"string"}}}},"coverImageUrl":{"description":"video Pins only — a render to use as the cover frame","type":"string"},"boardSectionId":{"description":"optional section within the board","type":"string"}},"required":["boardId"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"post_to_telegram","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"account":{"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.","type":"string"},"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."},"text":{"description":"the message. ≤4096 characters on its own; ≤1024 once any image or video is attached.","type":"string"},"imageUrl":{"description":"one image (≤10MB after upload)","type":"string"},"imageUrls":{"description":"an ALBUM of 2–10 media, in order. Photos and videos may be mixed — Telegram allows it.","type":"array","items":{"type":"string"}},"videoUrl":{"description":"one video (≤50MB). Passed alongside imageUrls it joins the album as one more item.","type":"string"},"disablePreview":{"description":"suppress the link-preview card on a text-only post. Default is Telegram’s own behaviour (previews on).","type":"boolean"},"silent":{"description":"deliver without a notification sound (Telegram’s disable_notification). This is NOT a visibility setting — the message is just as visible.","type":"boolean"}},"required":["chatId"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"post_to_tiktok","description":"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).","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"account":{"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.","type":"string"},"brand":{"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.","type":"string"},"hook":{"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.","type":"string"},"subject":{"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.","type":"string"},"videoUrl":{"description":"the video to post — a Hermoso render URL or an upload_file url. Omit for a photo post.","type":"string"},"imageUrls":{"description":"a PHOTO POST: 1–35 image URLs in slide order. One url = a single-image photo post. Do not combine with videoUrl.","type":"array","items":{"type":"string"}},"coverIndex":{"description":"photo posts: which slide is the cover, 0-based. Default 0 (the first slide).","type":"number"},"destination":{"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\".","type":"string","enum":["post","draft"]},"title":{"description":"the caption — hashtags go here (video ≤2200 chars, photo post ≤4000)","type":"string"},"photoTitle":{"description":"photo posts only: a short title above the caption (≤90 chars). Defaults to the caption’s first line.","type":"string"},"privacy":{"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.","type":"string","enum":["PUBLIC_TO_EVERYONE","MUTUAL_FOLLOW_FRIENDS","FOLLOWER_OF_CREATOR","SELF_ONLY"]},"disableComment":{"type":"boolean"},"disableDuet":{"description":"video only — TikTok has no duet on a photo post","type":"boolean"},"disableStitch":{"description":"video only — TikTok has no stitch on a photo post","type":"boolean"},"autoAddMusic":{"description":"photo posts only: let TikTok add a recommended track (default true — a silent slideshow reads as broken)","type":"boolean"},"coverTimestampMs":{"description":"video only: which frame to use as the cover, in ms","type":"number"},"aiGenerated":{"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.","type":"boolean"},"brandedContent":{"description":"discloses a paid partnership — cannot be combined with SELF_ONLY privacy","type":"boolean"},"yourBrand":{"description":"discloses that this promotes the creator’s own brand","type":"boolean"}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"post_to_x","description":"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).","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"account":{"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.","type":"string"},"brand":{"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.","type":"string"},"hook":{"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.","type":"string"},"subject":{"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.","type":"string"},"text":{"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.","type":"string"},"thread":{"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.","type":"array","items":{"type":"string"}},"mediaUrl":{"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","type":"string"},"videoUrl":{"description":"alias of mediaUrl for a VIDEO — same as passing it as mediaUrl","type":"string"},"imageUrl":{"description":"alias of mediaUrl for an IMAGE — same as passing it as mediaUrl","type":"string"},"mediaUrls":{"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.","type":"array","items":{"type":"string"}},"altText":{"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).","anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"poll":{"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.","type":"object","properties":{"options":{"type":"array","items":{"type":"string"},"description":"2-4 choices, max 25 characters each"},"durationMinutes":{"description":"5 to 10080 minutes (7 days); default 1440 = one day","type":"number"}},"required":["options"]},"replySettings":{"description":"restrict who can reply — omit for everyone, which is the right default for a brand post","type":"string","enum":["following","mentionedUsers","subscribers","verified"]},"replyToId":{"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.","type":"string"},"quotePostId":{"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.","type":"string"},"communityId":{"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.","type":"string"},"paidPartnership":{"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.","type":"boolean"}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"post_to_youtube","description":"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).","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"account":{"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.","type":"string"},"brand":{"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.","type":"string"},"hook":{"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.","type":"string"},"subject":{"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.","type":"string"},"videoUrl":{"type":"string","description":"the video to post — a Hermoso render URL or an upload_file url"},"title":{"description":"REQUIRED in practice — the headline every search result and the Shorts feed shows (≤100 chars); an upload with no title is refused","type":"string"},"description":{"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","type":"string"},"tags":{"description":"up to 30 tags","type":"array","items":{"type":"string"}},"thumbnailUrl":{"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.","type":"string"},"privacy":{"description":"default unlisted (anyone-with-link, ad-ready); public = live + searchable on the channel (confirm first); private = eyes-only (cannot run as an ad)","type":"string","enum":["private","unlisted","public"]},"categoryId":{"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.","type":"string"},"publishAt":{"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.","type":"string"},"notifySubscribers":{"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.","type":"boolean"},"aiGenerated":{"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.","type":"boolean"}},"required":["videoUrl"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"post_x_article","description":"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).","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"brand":{"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.","type":"string"},"hook":{"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.","type":"string"},"subject":{"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.","type":"string"},"title":{"type":"string","description":"the Article title — X requires one and refuses a draft without it. This is what shows on the timeline card."},"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."},"coverImageUrl":{"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.","type":"string"},"headings":{"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.","type":"string","enum":["blocks","text"]},"allowLossy":{"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.","type":"boolean"},"publish":{"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.","type":"boolean"}},"required":["title","body"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"product_sizzle","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"prompt":{"type":"string","description":"what the sizzle should show — the product, the setting, the look"},"seconds":{"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","type":"number"},"refImage":{"description":"product packshot URL that anchors the real label — strongly recommended","type":"string"},"aspectRatio":{"description":"'9:16' default; anything the seedance-2 catalog entry does not list falls back to 9:16","type":"string"},"resolution":{"description":"hero-clip resolution and therefore the whole cost — DEFAULT '1080p' (≈1,040 credits); '720p' ≈470, '480p' ≈220, '4k' ≈4,130","type":"string","enum":["480p","720p","1080p","4k"]},"specs":{"description":"up to 4 spec lines for the typeset cards, ≤26 chars each","type":"array","items":{"type":"string"}},"cta":{"description":"closing CTA line, ≤30 chars","type":"string"},"brandName":{"description":"brand name on the cards — defaults to the workspace brand","type":"string"},"musicMood":{"description":"music-bed mood, e.g. driving / cinematic / upbeat","type":"string"}},"required":["prompt"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"publish_to_shopify_product","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"productId":{"type":"string","description":"gid://shopify/Product/… from list_shopify_products"},"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"},"alt":{"description":"alt text for accessibility and SEO; defaults to a generic credit","type":"string"}},"required":["productId","imageUrl"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"pull_competitor_ads","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"companyName":{"description":"the advertiser name","type":"string"},"domain":{"description":"the advertiser domain","type":"string"},"country":{"description":"2-letter, default 'US'","type":"string"},"limit":{"description":"max ads per platform (default 30)","type":"number"},"sort":{"description":"'longest_running' (default) etc.","type":"string"}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"read_doc","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"documentId":{"description":"the document id (from create_doc)","type":"string"},"docUrl":{"description":"a Google Docs URL to read — the document id is extracted from it","type":"string"}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"read_sheet","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"spreadsheetId":{"description":"the spreadsheet id (from create_sheet)","type":"string"},"sheetUrl":{"description":"a Google Sheets URL to read — the spreadsheet id is extracted from it","type":"string"},"range":{"description":"A1 range, e.g. \"A1:D50\" (default A1:Z1000)","type":"string"}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"recast_motion","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"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":{"description":"optional scene/style guidance","type":"string"},"orientation":{"description":"which aspect to keep: the video's (default) or the image's","type":"string","enum":["video","image"]}},"required":["image","video"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"reframe_video","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"video":{"type":"string","description":"the source video URL"},"aspectRatio":{"type":"string","enum":["9:16","1:1","16:9","4:3","3:4","21:9","9:21"],"description":"the target aspect ratio"}},"required":["video","aspectRatio"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"remember","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"text":{"type":"string","description":"the fact/preference, concise"},"category":{"description":"short bucket: Brand, Audience, Taste, Do, Don’t, or Preference (default General)","type":"string"}},"required":["text"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"remix_static","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"imageUrl":{"type":"string","description":"the URL of the static ad image to clone"},"brandId":{"description":"a brand id/name from list_brands to clone for; omit to use the active brand","type":"string"}},"required":["imageUrl"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"remove_member","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"email":{"type":"string","description":"the member’s email"},"confirm":{"description":"REQUIRED true","type":"boolean"}},"required":["email"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"render_ad","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"creative":{"type":"object","properties":{},"additionalProperties":{},"description":"the FULL structured output of plan_ad (must contain video_storyboard)"},"creator":{"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.","type":"string"},"model":{"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)","type":"string"},"durationSeconds":{"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.","type":"number"},"aspectRatio":{"description":"output aspect ratio, e.g. 9:16 (default) / 1:1 / 16:9","type":"string"},"resolution":{"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.","type":"string","enum":["480p","720p","1080p","4k"]},"captions":{"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","type":"boolean"},"endCard":{"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)","type":"boolean"},"music":{"description":"licensed music bed on/off (default on)","type":"boolean"},"lockup":{"description":"brand wordmark + tagline composited over the closing seconds. DEFAULT FALSE — set true ONLY when the user asks for branding on the close","type":"boolean"},"textStyle":{"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.","anyOf":[{"type":"string","enum":["pill","editorial","bold","minimal","handwritten","boxed"]},{"type":"object","properties":{"preset":{"type":"string","enum":["pill","editorial","bold","minimal","handwritten","boxed"]},"font":{"type":"string","enum":["sans","serif","elegant","condensed","hand"]},"subFont":{"type":"string","enum":["sans","serif","elegant","condensed","hand"]},"weight":{"type":"number"},"size":{"anyOf":[{"type":"string","enum":["s","m","l","xl"]},{"type":"number"}]},"color":{"description":"#hex","type":"string"},"background":{"description":"\"none\", \"pill\", or a #hex box","type":"string"},"position":{"type":"string","enum":["top","center","lower","bottom"]},"textCase":{"type":"string","enum":["as-is","upper","lower","title"]},"italic":{"type":"boolean"},"subItalic":{"type":"boolean"},"outline":{"type":"boolean"},"shadow":{"type":"boolean"},"tilt":{"description":"degrees, ±12","type":"number"},"cardColor":{"description":"#hex end card background","type":"string"}}}]},"ttsVoice":{"description":"voiceover voice name (e.g. Rachel / George) when the plan voices over","type":"string"},"dryRun":{"description":"return the routing decision (single pass vs stitched acts, resolved model + act lengths) WITHOUT submitting a render — free, nothing charged","type":"boolean"},"allowGenericProduct":{"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","type":"boolean"}},"required":["creative"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"report_bug","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"summary":{"type":"string","description":"one-line summary of the bug"},"details":{"type":"string","description":"what you were doing, the tool + arguments you called, what you expected, and what actually happened (paste the exact error)"},"severity":{"description":"high = blocks the task or loses paid work; medium = wrong output but workable; low = cosmetic","type":"string","enum":["low","medium","high"]}},"required":["summary","details"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"request_feature","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"summary":{"type":"string","description":"one line: the capability you need"},"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"}},"required":["summary","details"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"reschedule_post","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"brand":{"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.","type":"string"},"id":{"type":"string","description":"the scheduled post id from list_scheduled"},"at":{"description":"the new time — ISO timestamp (2026-08-05T09:00:00Z) or epoch milliseconds. Must be in the future, at most 365 days out.","type":"string"},"message":{"description":"replace the caption used for every channel that has no override","type":"string"},"captions":{"description":"replaces the WHOLE per-channel caption map — send every override you want to keep, not just the new one","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"optimizeCopy":{"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.","type":"boolean"},"channels":{"description":"replaces the channel list","type":"array","items":{"type":"string","enum":["facebook","instagram","threads","tiktok","youtube","linkedin","x","pinterest","google_business","bluesky","telegram"]}},"imageUrl":{"description":"swap the image; \"\" removes it","type":"string"},"videoUrl":{"description":"swap the video; \"\" removes it","type":"string"},"imageUrls":{"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.","type":"array","items":{"type":"string"}},"title":{"description":"PINTEREST / YOUTUBE — replace the headline; \"\" clears it and goes back to deriving one from the caption","type":"string"},"description":{"description":"YOUTUBE — replace the video description; \"\" clears it and the caption is used.","type":"string"},"tags":{"description":"YOUTUBE — replaces the WHOLE tag list; an empty array [] clears the tags.","type":"array","items":{"type":"string"}},"thumbnailUrl":{"description":"YOUTUBE: replace the custom thumbnail; \"\" goes back to a frame of the video, \"auto\" to YouTube’s pick.","type":"string"},"replyControl":{"description":"THREADS ONLY — who may reply.","type":"string","enum":["everyone","accounts_you_follow","mentioned_only","parent_post_author_only","followers_only"]},"quotePostId":{"description":"THREADS ONLY — the id of the Threads post this one quotes.","type":"string"},"linkAttachment":{"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.","type":"string"},"topicTag":{"description":"THREADS ONLY — one topic tag, without the leading #.","type":"string"},"countryCodes":{"description":"THREADS ONLY — two-letter country codes limiting who can see the post.","type":"array","items":{"type":"string"}},"crossreshareToIg":{"description":"THREADS ONLY — also share to Instagram as a Story when it fires; false turns it off. Refused on a carousel.","type":"boolean"},"crossreshareDarkMode":{"description":"THREADS ONLY — dark-mode that Instagram Story. Needs crossreshareToIg.","type":"boolean"},"slideText":{"description":"PINTEREST CAROUSEL ONLY — per-slide title / description / link, aligned to slide order.","type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"link":{"type":"string"}}}},"privacyLevel":{"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.","type":"string","enum":["PUBLIC_TO_EVERYONE","MUTUAL_FOLLOW_FRIENDS","FOLLOWER_OF_CREATOR","SELF_ONLY"]},"altText":{"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.","anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"link":{"type":"string"},"brandedContent":{"description":"TIKTOK — the paid-partnership disclosure; false turns it off.","type":"boolean"},"yourBrand":{"description":"TIKTOK — the own-brand disclosure; false turns it off.","type":"boolean"},"commercialContent":{"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.","type":"boolean"},"disableComment":{"description":"TIKTOK — comments off on this post.","type":"boolean"},"disableDuet":{"description":"TIKTOK VIDEO ONLY — block Duets.","type":"boolean"},"disableStitch":{"description":"TIKTOK VIDEO ONLY — block Stitches.","type":"boolean"},"coverTimestampMs":{"description":"TIKTOK VIDEO ONLY — cover frame in milliseconds.","type":"number"},"topicType":{"description":"GOOGLE BUSINESS — the kind of Post; EVENT and OFFER both require `event`.","type":"string","enum":["STANDARD","EVENT","OFFER","ALERT"]},"actionType":{"description":"GOOGLE BUSINESS — the call-to-action button; \"\" clears it.","type":"string","enum":["BOOK","ORDER","SHOP","LEARN_MORE","SIGN_UP","CALL"]},"event":{"description":"GOOGLE BUSINESS — replaces the whole event record {title, startDate, startTime, endDate, endTime}.","type":"object","properties":{"title":{"type":"string"},"startDate":{"type":"string"},"startTime":{"type":"string"},"endDate":{"type":"string"},"endTime":{"type":"string"}}},"offer":{"description":"GOOGLE BUSINESS — replaces the whole offer record {couponCode, redeemOnlineUrl, termsConditions}.","type":"object","properties":{"couponCode":{"type":"string"},"redeemOnlineUrl":{"type":"string"},"termsConditions":{"type":"string"}}},"thread":{"description":"X — replaces the WHOLE thread; an explicit [] drops back to a single post using the caption.","type":"array","items":{"type":"string"}},"poll":{"description":"X — replaces the poll; an empty options list removes it.","type":"object","properties":{"options":{"type":"array","items":{"type":"string"}},"durationMinutes":{"type":"number"}},"required":["options"]},"replySettings":{"description":"X — who may reply; \"\" goes back to everyone.","type":"string","enum":["following","mentionedUsers","subscribers","verified"]},"madeWithAi":{"description":"X — the AI-media label; false turns it off.","type":"boolean"},"xQuotePostId":{"description":"X — the post this one QUOTES; an empty string removes the quote. Named apart from the Threads `quotePostId` on this same schedule.","type":"string"},"communityId":{"description":"X — the community to publish into; an empty string goes back to the main timeline.","type":"string"},"paidPartnership":{"description":"INSTAGRAM AND X — the paid-partnership label; false turns it off.","type":"boolean"},"xArticle":{"description":"X: replaces the X Article (title, headings); {} makes it an ordinary X post again.","type":"object","properties":{"title":{"type":"string"},"headings":{"type":"string","enum":["blocks","text"]}}},"collaborators":{"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.","type":"array","items":{"type":"string"}},"trialReel":{"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.","type":"string","enum":["MANUAL","SS_PERFORMANCE",""]},"story":{"description":"INSTAGRAM — true makes it a 24-hour Story, false an ordinary feed post. One image or one video, no carousel.","type":"boolean"},"coverUrl":{"description":"INSTAGRAM REEL — replaces the cover image url; an empty string removes it.","type":"string"},"thumbOffset":{"description":"INSTAGRAM REEL — replaces the cover frame, in milliseconds; 0 removes it. Never together with coverUrl.","type":"number"},"shareToFeed":{"description":"INSTAGRAM REEL — whether the Reel also shows in the Feed grid.","type":"boolean"},"audioName":{"description":"INSTAGRAM REEL — replaces the audio track name; an empty string removes it.","type":"string"},"instagramLocationId":{"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.","type":"string"},"brandedContentSponsorIds":{"description":"INSTAGRAM — replaces the sponsor user ids behind the paid-partnership label (at most 2); [] removes them.","type":"array","items":{"type":"string"}},"place":{"description":"FACEBOOK — replaces the tagged place (the numeric id of its Facebook Page); an empty string removes it.","type":"string"},"callToAction":{"description":"FACEBOOK — replaces the button on the Page post; \"\" removes it.","type":"string","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",""]},"callToActionLink":{"description":"FACEBOOK — replaces where the button goes; an empty string falls back to the post link.","type":"string"},"linkName":{"description":"FACEBOOK — replaces the link preview headline; an empty string removes the override.","type":"string"},"linkDescription":{"description":"FACEBOOK — replaces the link preview description; an empty string removes the override.","type":"string"},"linkPicture":{"description":"FACEBOOK — replaces the link preview image url; an empty string removes the override.","type":"string"},"audience":{"description":"FACEBOOK — replaces who can see the Page post {countries, regions, cities, minAge}; {} removes the limit.","type":"object","properties":{"countries":{"type":"array","items":{"type":"string"}},"regions":{"type":"array","items":{"type":"string"}},"cities":{"type":"array","items":{"type":"string"}},"minAge":{"type":"number"}}},"targetAudience":{"description":"LINKEDIN COMPANY PAGE — replaces who sees the post; {} removes the limit. The matching audience must be over 300 followers.","type":"object","properties":{"geoLocations":{"type":"array","items":{"type":"string"}},"industries":{"type":"array","items":{"type":"string"}},"seniorities":{"type":"array","items":{"type":"string"}},"jobFunctions":{"type":"array","items":{"type":"string"}},"staffCountRanges":{"type":"array","items":{"type":"string"}},"degrees":{"type":"array","items":{"type":"string"}},"fieldsOfStudy":{"type":"array","items":{"type":"string"}},"organizations":{"type":"array","items":{"type":"string"}}}},"aiGenerated":{"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.","type":"boolean"},"boardId":{"description":"PINTEREST — move the Pin to a different board (list_pinterest_boards)","type":"string"},"chatId":{"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.","type":"string"},"linkedinOrganizationId":{"description":"LINKEDIN — target a different company Page, or \"\" to post as the connected person instead","type":"string"},"pageId":{"description":"FACEBOOK / INSTAGRAM / THREADS — publish from a different connected Page (list_meta_pages)","type":"string"},"locationId":{"description":"GOOGLE BUSINESS — a different listing (list_business_locations)","type":"string"},"visibility":{"description":"NOTE: changing this without also naming visibilityByChannel clears any per-channel overrides, so \"make it all draft\" is not a no-op","type":"string","enum":["public","unlisted","private","draft"]},"visibilityByChannel":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}}},"required":["id"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"research_ads","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"query":{"type":"string","description":"what to research, e.g. \"the longest-running protein-pancake ads on Meta\""},"brand":{"description":"brand name or profile object to tailor the research to; omit to use the workspace’s saved brand","anyOf":[{"type":"string"},{"type":"object","properties":{},"additionalProperties":{}}]}},"required":["query"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"retry_scheduled","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"brand":{"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.","type":"string"},"id":{"type":"string","description":"the scheduled post id from list_scheduled"},"channels":{"description":"retry only these channels (default: every channel that did not publish)","type":"array","items":{"type":"string","enum":["facebook","instagram","threads","tiktok","youtube","linkedin","x","pinterest","google_business","bluesky","telegram"]}},"at":{"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.","type":"string"},"allowDuplicate":{"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.","type":"boolean"},"boardId":{"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.","type":"string"},"chatId":{"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.","type":"string"},"pageId":{"description":"CORRECT THE PAGE on retry — which connected Facebook Page (and its linked Instagram/Threads) publishes, from list_meta_pages.","type":"string"},"linkedinOrganizationId":{"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.","type":"string"},"locationId":{"description":"CORRECT THE LISTING on retry — which Google Business Profile location, e.g. \"locations/123\" from list_business_locations.","type":"string"},"message":{"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.","type":"string"},"captions":{"description":"CORRECT ONE CHANNEL’S CAPTION on retry, e.g. { \"x\": \"...\" } when only that channel refused the text.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}}},"required":["id"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"run_post_refill","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"dryRun":{"description":"default TRUE (preview only). false actually queues the posts.","type":"boolean"},"force":{"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.","type":"boolean"}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"save_creator","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"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"},"source":{"description":"\"generated\" (default) = an AI-made person; \"upload\" / \"social\" = a REAL person","type":"string","enum":["generated","upload","social"]},"consented":{"description":"REAL people only: the user has confirmed that person consented to their likeness being used in ads","type":"boolean"},"voice":{"description":"a default voice name for this persona (engines + voices are in hermoso_capabilities)","type":"string"},"poses":{"description":"up to 4 extra full-body / angle plates of the SAME person (public urls) — they make a wider shot hold the identity","type":"array","items":{"type":"string"}},"look":{"description":"their canonical wardrobe/appearance in words — reused to hold the look steady across ads","type":"string"}},"required":["name","image"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"save_playbook","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"name":{"type":"string","description":"the playbook headline — what it is, in a few words"},"hooks":{"description":"the opening hooks worth reusing, verbatim","type":"array","items":{"type":"string"}},"angles":{"description":"the persuasion angles ({title, detail})","type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"detail":{"type":"string"}},"required":["title"],"additionalProperties":{}}},"formats":{"description":"the formats/recipes this plays best in (e.g. ugc_selfie, cinematic, static)","type":"array","items":{"type":"string"}},"plays":{"description":"the concrete plays to run ({title, detail}) — the actionable half","type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"detail":{"type":"string"}},"required":["title"],"additionalProperties":{}}},"brand":{"description":"which brand this is for (defaults to the workspace brand)","type":"string"},"source":{"description":"where it came from, e.g. “teardown · Ridge”","type":"string"}},"required":["name"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"save_skill","description":"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).","write_action":false,"price_micros":0,"input_schema":{"type":"object","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)"}},"required":["name","directive"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"save_to_drive","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"url":{"description":"a single Hermoso render URL to save","type":"string"},"urls":{"description":"several render URLs (up to 20) to save in one call","type":"array","items":{"type":"string"}},"folder":{"description":"Drive folder name to save into (created if new)","type":"string"},"name":{"description":"file name (single save)","type":"string"}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"save_to_onedrive","description":"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).","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"url":{"description":"a single Hermoso render URL to save","type":"string"},"urls":{"description":"several render URLs (up to 20) to save in one call","type":"array","items":{"type":"string"}},"folder":{"description":"OneDrive folder name to save into (created if new)","type":"string"},"name":{"description":"file name (single save)","type":"string"}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"save_to_swipefile","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"collection":{"type":"string","description":"the collection name — an existing one, or a new one to create"},"items":{"minItems":1,"type":"array","items":{"type":"object","properties":{"key":{"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","type":"string"},"advertiser":{"description":"the brand running the ad","type":"string"},"page_name":{"description":"alias of advertiser: the field search_meta_ads returns, accepted as-is","type":"string"},"pageName":{"description":"alias of advertiser","type":"string"},"title":{"description":"headline / hook","type":"string"},"body":{"description":"the ad copy","type":"string"},"image":{"description":"image URL","type":"string"},"video":{"description":"video URL","type":"string"},"link":{"description":"link to the ad in its library / the destination URL","type":"string"},"platform":{"description":"where it ran — 'meta', 'google', 'linkedin', 'tiktok', 'generated', …","type":"string"}},"additionalProperties":{}},"description":"the ads to save"}},"required":["collection","items"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"schedule_post","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"brand":{"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.","type":"string"},"hook":{"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.","type":"string"},"subject":{"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.","type":"string"},"channels":{"type":"array","items":{"type":"string","enum":["facebook","instagram","threads","tiktok","youtube","linkedin","x","pinterest","google_business","bluesky","telegram"]},"description":"one or more channels to post to at that time"},"at":{"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.","type":"string"},"useQueue":{"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.","type":"boolean"},"timezone":{"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.","type":"string"},"message":{"description":"the caption/text used for every channel unless overridden in captions","type":"string"},"captions":{"description":"per-channel caption overrides, e.g. { \"instagram\": \"…\", \"threads\": \"…\" } — platforms want different lengths and hashtag conventions","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"accounts":{"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).","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"string","const":"all"}]}},"imageUrl":{"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.","type":"string"},"videoUrl":{"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.","type":"string"},"imageUrls":{"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.","type":"array","items":{"type":"string"}},"title":{"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.","type":"string"},"description":{"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.","type":"string"},"tags":{"description":"YOUTUBE — up to 30 search tags for the video (plain words, no #).","type":"array","items":{"type":"string"}},"thumbnailUrl":{"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.","type":"string"},"replyControl":{"description":"THREADS ONLY — who may reply. Omit for Threads' own default (everyone).","type":"string","enum":["everyone","accounts_you_follow","mentioned_only","parent_post_author_only","followers_only"]},"quotePostId":{"description":"THREADS ONLY — the id of the Threads post this one quotes.","type":"string"},"linkAttachment":{"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).","type":"string"},"topicTag":{"description":"THREADS ONLY — one topic tag for the post, without the leading #.","type":"string"},"countryCodes":{"description":"THREADS ONLY — two-letter country codes to limit who can see the post. Omit to show it everywhere.","type":"array","items":{"type":"string"}},"crossreshareToIg":{"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.","type":"boolean"},"crossreshareDarkMode":{"description":"THREADS ONLY — render that Instagram Story in dark mode. Needs crossreshareToIg.","type":"boolean"},"slideText":{"description":"PINTEREST CAROUSEL ONLY — per-slide title / description / link, aligned to slide order. Every other platform takes ONE caption for the whole carousel.","type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"link":{"type":"string"}}}},"altText":{"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.","anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"link":{"description":"a link to attach (Facebook)","type":"string"},"brandedContent":{"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.","type":"boolean"},"yourBrand":{"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.","type":"boolean"},"privacyLevel":{"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.","type":"string","enum":["PUBLIC_TO_EVERYONE","MUTUAL_FOLLOW_FRIENDS","FOLLOWER_OF_CREATOR","SELF_ONLY"]},"commercialContent":{"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.","type":"boolean"},"disableComment":{"description":"TIKTOK — turn comments off on this post.","type":"boolean"},"disableDuet":{"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.","type":"boolean"},"disableStitch":{"description":"TIKTOK VIDEO ONLY — block Stitches. Same photo-post rule as disableDuet.","type":"boolean"},"coverTimestampMs":{"description":"TIKTOK VIDEO ONLY — which frame TikTok uses as the cover, in milliseconds from the start. Omit and TikTok uses the first frame.","type":"number"},"topicType":{"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`.","type":"string","enum":["STANDARD","EVENT","OFFER","ALERT"]},"actionType":{"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.","type":"string","enum":["BOOK","ORDER","SHOP","LEARN_MORE","SIGN_UP","CALL"]},"event":{"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.","type":"object","properties":{"title":{"type":"string"},"startDate":{"type":"string"},"startTime":{"type":"string"},"endDate":{"type":"string"},"endTime":{"type":"string"}}},"offer":{"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.","type":"object","properties":{"couponCode":{"type":"string"},"redeemOnlineUrl":{"type":"string"},"termsConditions":{"type":"string"}}},"thread":{"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.","type":"array","items":{"type":"string"}},"poll":{"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.","type":"object","properties":{"options":{"type":"array","items":{"type":"string"}},"durationMinutes":{"type":"number"}},"required":["options"]},"replySettings":{"description":"X — who may reply. Omit for everyone, which is the right default for a brand post.","type":"string","enum":["following","mentionedUsers","subscribers","verified"]},"madeWithAi":{"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.","type":"boolean"},"xQuotePostId":{"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.","type":"string"},"communityId":{"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.","type":"string"},"paidPartnership":{"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.","type":"boolean"},"xArticle":{"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.","type":"object","properties":{"title":{"type":"string"},"headings":{"type":"string","enum":["blocks","text"]}},"required":["title"]},"collaborators":{"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.","type":"array","items":{"type":"string"}},"audience":{"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.","type":"object","properties":{"countries":{"description":"two-letter codes, e.g. [\"CA\",\"US\"]","type":"array","items":{"type":"string"}},"regions":{"description":"Meta location keys for regions/states","type":"array","items":{"type":"string"}},"cities":{"description":"Meta location keys for cities","type":"array","items":{"type":"string"}},"minAge":{"anyOf":[{"type":"number","const":13},{"type":"number","const":15},{"type":"number","const":18},{"type":"number","const":21},{"type":"number","const":25}]}}},"targetAudience":{"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.","type":"object","properties":{"geoLocations":{"type":"array","items":{"type":"string"}},"industries":{"type":"array","items":{"type":"string"}},"seniorities":{"type":"array","items":{"type":"string"}},"jobFunctions":{"type":"array","items":{"type":"string"}},"staffCountRanges":{"type":"array","items":{"type":"string","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"]}},"degrees":{"type":"array","items":{"type":"string"}},"fieldsOfStudy":{"type":"array","items":{"type":"string"}},"organizations":{"type":"array","items":{"type":"string"}}}},"place":{"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.","type":"string"},"callToAction":{"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.","type":"string","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"]},"callToActionLink":{"description":"FACEBOOK — where the button goes, when that is not the post’s own `link`.","type":"string"},"linkName":{"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.","type":"string"},"linkDescription":{"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.","type":"string"},"linkPicture":{"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.","type":"string"},"coverUrl":{"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.","type":"string"},"thumbOffset":{"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.","type":"number"},"shareToFeed":{"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.","type":"boolean"},"audioName":{"description":"INSTAGRAM REEL — the name of the Reel’s audio track, which is what viewers tap through to. REELS ONLY.","type":"string"},"instagramLocationId":{"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.","type":"string"},"brandedContentSponsorIds":{"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.","type":"array","items":{"type":"string"}},"trialReel":{"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.","type":"string","enum":["MANUAL","SS_PERFORMANCE"]},"story":{"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.","type":"boolean"},"aiGenerated":{"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.","type":"boolean"},"boardId":{"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.","type":"string"},"chatId":{"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.","type":"string"},"linkedinOrganizationId":{"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.","type":"string"},"pageId":{"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.","type":"string"},"locationId":{"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.","type":"string"},"visibility":{"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.","type":"string","enum":["public","unlisted","private","draft"]},"visibilityByChannel":{"description":"override visibility for one channel, e.g. { \"tiktok\": \"draft\" } to go live everywhere but stage TikTok for review","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"optimizeCopy":{"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.","type":"boolean"}},"required":["channels"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"score_ad","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"url":{"type":"string","description":"the ad asset URL (a /generated/ path or public URL)"},"kind":{"description":"'image' (default) or 'video'","type":"string","enum":["image","video"]},"intent":{"description":"what the ad is trying to achieve, for goal-fit scoring","type":"string"}},"required":["url"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"search_google_ads","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"domain":{"description":"the advertiser's domain, e.g. nike.com","type":"string"},"advertiserId":{"description":"Google advertiser id (AR…) when the domain is ambiguous","type":"string"},"region":{"description":"2-letter region, default US","type":"string"},"limit":{"description":"max ads returned (1–25, default 8)","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"search_instagram","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"query":{"type":"string","description":"keyword to search reels for"},"limit":{"description":"max reels returned (1–25, default 8)","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["query"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"search_linkedin_ads","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"company":{"description":"advertiser company name","type":"string"},"keyword":{"description":"keyword across all advertisers","type":"string"},"companyId":{"description":"LinkedIn company id (numeric) when the name is ambiguous","type":"string"},"countries":{"description":"CSV of 2-letter codes like 'US,CA'; omit or 'ALL' = worldwide","type":"string"},"limit":{"description":"max ads returned (1–25, default 8)","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"search_meta_ads","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"query":{"description":"keyword search across ALL advertisers (use INSTEAD of companyName/pageId)","type":"string"},"companyName":{"description":"one advertiser’s ads by brand name","type":"string"},"pageId":{"description":"one advertiser’s ads by Facebook page id (most precise)","type":"string"},"country":{"description":"2-letter code or 'ALL' (default ALL)","type":"string"},"status":{"description":"ACTIVE = currently running; default ALL (includes proven past winners)","type":"string","enum":["ACTIVE","INACTIVE","ALL"]},"mediaType":{"description":"filter by creative type (default ALL)","type":"string","enum":["ALL","IMAGE","VIDEO","MEME","IMAGE_AND_MEME","NONE"]},"limit":{"description":"max ads returned (1–25, default 8)","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"search_posts","description":"The POSTS people make ABOUT a subject — a brand (\"higgsfield\"), 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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"topic":{"type":"string","description":"subject, brand, product or hashtag — \"higgsfield\", \"coffee\", \"#homecafe\""},"platforms":{"description":"default all three","type":"array","items":{"type":"string","enum":["tiktok","instagram","youtube"]}},"limit":{"description":"posts per platform, 1–60 (default 24)","type":"number"},"queries":{"description":"query variants per platform, 1–4 (default 1); each is a paid search call","type":"number"}},"required":["topic"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"search_reddit","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"query":{"type":"string","description":"what to search Reddit for"},"limit":{"description":"max posts returned (1–25, default 8)","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["query"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"search_threads","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"query":{"type":"string","description":"keyword to search Threads for"},"limit":{"description":"max posts returned (1–25, default 8)","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["query"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"search_tiktok","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"query":{"type":"string","description":"keyword or hashtag (no # needed)"},"limit":{"description":"max videos returned (1–25, default 8)","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["query"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"search_youtube","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"query":{"type":"string","description":"keyword to search videos for"},"limit":{"description":"max videos returned (1–25, default 8)","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["query"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"set_auto_reload","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"enabled":{"type":"boolean","description":"true to turn auto-reload on, false to turn it off"},"thresholdCredits":{"description":"reload when the balance drops below this many credits","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"reloadCredits":{"description":"how many credits to add each reload — must match a credit pack size (see buy_credits)","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["enabled"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"set_competitor_watch","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"competitors":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"the brand name, as it advertises"},"domain":{"description":"its domain, e.g. ridge.com — required for Google Ads Transparency, and what disambiguates a common brand name on Meta","type":"string"}},"required":["name"],"additionalProperties":{}},"description":"the brands to watch — the COMPLETE list, replacing whatever was set before. Empty array = stop watching."},"runNow":{"description":"true to run one check immediately (spends credits now) instead of waiting a week for the first one","type":"boolean"}},"required":["competitors"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"set_connector_accounts","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"provider":{"type":"string","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"],"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"}},"required":["provider","accountIds"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"set_post_refill","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"enabled":{"description":"on/off. false PAUSES it: the recurring job is deleted and nothing new is queued. Already-queued posts are untouched.","type":"boolean"},"dryRun":{"description":"true (the default) = plan and preview only, queue nothing. Set false ONLY after a human has read a preview.","type":"boolean"},"daysAhead":{"description":"how far ahead to keep the queue full, 1–30 (default 7)","type":"number"},"postsPerDay":{"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.","type":"number"},"assetCooldownDays":{"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.","type":"number"},"maxImagesPerDay":{"description":"how many NEW images a day it may render when the Library runs dry. 0 (default) = none, spend nothing.","type":"number"},"maxVideosPerDay":{"description":"how many NEW videos a day it may render. 0 (default) = none. Video is the expensive one — hundreds of credits each.","type":"number"},"maxCreditsPerDay":{"description":"a hard credit ceiling per day, checked BEFORE any render starts. It binds independently of the counts above.","type":"number"},"channels":{"description":"restrict it to these channels. Omit (or send an empty list) to use every connected channel that can carry each post.","type":"array","items":{"type":"string","enum":["facebook","instagram","threads","tiktok","youtube","linkedin","x","pinterest","google_business","bluesky","telegram"]}},"boardId":{"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.","type":"string"},"chatId":{"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.","type":"string"},"linkedinOrganizationId":{"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.","type":"string"},"pageId":{"description":"FACEBOOK / INSTAGRAM / THREADS — which connected Page to publish from (list_meta_pages). Omit for the brand’s only Page.","type":"string"}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"set_product_image","description":"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).","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"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":{"description":"a short note on where it came from, e.g. \"from their IG post\"","type":"string"},"brandId":{"description":"a brand id/name from list_brands to lock the product for; omit to use the active brand","type":"string"}},"required":["imageUrl"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"set_role","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"email":{"type":"string","description":"the member’s email"},"role":{"type":"string","enum":["admin","member"],"description":"the new role"},"confirm":{"description":"REQUIRED true","type":"boolean"}},"required":["email","role"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"stitch_video","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"scenes":{"minItems":2,"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}},"description":"array of scene objects (visual + optional voiceover/seconds)"},"aspectRatio":{"description":"output aspect ratio, e.g. 9:16 (default) / 1:1 / 16:9","type":"string"},"voiceover":{"description":"full voiceover script spoken across the scenes","type":"string"},"voice":{"description":"voiceover voice name, e.g. Rachel / George","type":"string"},"resolution":{"description":"720p (default), 1080p for full detail, or 480p for a cheaper draft","type":"string"},"model":{"description":"video model id from hermoso_capabilities — omit to let the router pick","type":"string"},"durationSeconds":{"description":"total spot length in seconds (defaults to the sum of the scenes’ seconds)","type":"number"}},"required":["scenes"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"store_get","description":"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.)","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"key":{"type":"string","description":"the store key to read (one of the allowlisted keys)"},"limit":{"description":"max array items to return (default 50)","type":"number"}},"required":["key"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"subscribe_linkedin_leads","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"forwardTo":{"description":"optional public HTTPS URL Hermoso relays each lead event to (a CRM, Zapier, Make)","type":"string"},"pageId":{"description":"the company Page that owns the form — from list_linkedin_pages; omit when one Page is shared","type":"string"},"adAccountId":{"description":"read forms owned by an AD ACCOUNT instead of a Page","type":"string"},"leadType":{"description":"defaults by owner: SPONSORED for an ad account, COMPANY for a Page","type":"string","enum":["SPONSORED","COMPANY","EVENT","ORGANIZATION_PRODUCT"]}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"tidy_memory","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"confirm":{"description":"true to APPLY the proposal; omit to only see it","type":"boolean"}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"update_brand","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"name":{"type":"string"},"domain":{"description":"website domain","type":"string"},"sells":{"description":"what the brand sells","type":"string"},"summary":{"description":"one-line description","type":"string"},"category":{"type":"string"},"audience":{"type":"string"},"positioning":{"type":"string"},"voice":{"description":"brand voice/tone","type":"string"},"style":{"description":"visual style — palette, typography, aesthetic","type":"string"},"goal":{"description":"current marketing goal","type":"string"}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"update_doc","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"documentId":{"description":"the document id (from create_doc, or list_drive_files for one the user picked)","type":"string"},"docUrl":{"description":"a Google Docs URL — the id is extracted from it","type":"string"},"replacements":{"description":"find/replace pairs, applied in order","type":"array","items":{"type":"object","properties":{"find":{"type":"string"},"replace":{"type":"string"},"matchCase":{"type":"boolean"}},"required":["find"]}},"rewrite":{"description":"replace the WHOLE body with this text (\"\" empties the doc)","type":"string"},"confirm":{"type":"boolean"},"confirmCells":{"description":"echo back the character count the unconfirmed call reported (rewrite only)","type":"number"}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"update_drive_file","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"fileId":{"type":"string","description":"the Drive file id"},"name":{"description":"new name","type":"string"},"moveToFolderId":{"description":"folder id to move the file into (from create_drive_folder / list_drive_files)","type":"string"},"removeFromFolderId":{"description":"the old parent folder id to remove (when moving)","type":"string"},"trash":{"description":"true → move to Trash; false → restore from Trash","type":"boolean"}},"required":["fileId"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"update_onedrive_file","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"fileId":{"type":"string","description":"the OneDrive item id"},"name":{"description":"new name","type":"string"},"moveToFolderId":{"description":"folder id to move the item into (from create_onedrive_folder / list_onedrive_files)","type":"string"}},"required":["fileId"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"update_saved_creator","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"key":{"type":"string","description":"the saved row's key from list_swipefile, e.g. tiktok:handle"},"status":{"type":"string","enum":["new","contacted","replied","booked","passed"]},"note":{"description":"replaces the existing note; pass \"\" to clear it","type":"string","maxLength":2000}},"required":["key"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"update_settings","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"language":{"description":"language for generated ads, copy and answers — e.g. \"English\", \"German\", \"Japanese\"","type":"string"},"theme":{"description":"app appearance","type":"string","enum":["dark","light"]},"watchEmail":{"description":"weekly competitor-watch email on/off","type":"boolean"}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"update_sheet","description":"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.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"spreadsheetId":{"type":"string"},"sheetUrl":{"type":"string"},"range":{"description":"A1 range or anchor cell, e.g. \"B2:C5\", \"B2\", or \"Q3 Report!B2\" (default A1)","type":"string"},"values":{"description":"array of row arrays to write","type":"array","items":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}}},"updates":{"description":"write SEVERAL disjoint ranges in one call, instead of range+values","type":"array","items":{"type":"object","properties":{"range":{"type":"string"},"values":{"type":"array","items":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}}}}}},"valueInputOption":{"description":"USER_ENTERED (default) parses formulas, dates and numbers the way typing them would; RAW stores every value as literal text","type":"string","enum":["USER_ENTERED","RAW"]},"confirm":{"description":"required only when the target range already holds values","type":"boolean"}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"upgrade_plan","description":"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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"plan":{"description":"the plan id to move to (e.g. pro) — omit to list the available plans first","type":"string"},"period":{"description":"billing cadence — monthly (default) or yearly (2 months free)","type":"string","enum":["mo","yr"]}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"upload_file","description":"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}.","write_action":true,"price_micros":0,"input_schema":{"type":"object","properties":{"getUploadUrl":{"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.","type":"boolean"},"url":{"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.","type":"string"},"dataUri":{"description":"base64 data: URI of the file bytes (data:<mime>;base64,<…>) — bytes travel over this connection, so keep it small","type":"string"},"name":{"description":"original file name — helps pick the right extension","type":"string"}},"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"upscale_video","description":"Upscale a video to higher resolution (2x) for final delivery. Paid render; returns the served URL. Two engines: the default (Topaz) 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.","write_action":false,"price_micros":0,"input_schema":{"type":"object","properties":{"video":{"type":"string","description":"the source video URL"},"engine":{"description":"default topaz. 'flux' = the FLUX 3 video upscaler","type":"string","enum":["topaz","flux"]},"mode":{"description":"FLUX only — 'creative' turns on its detail-enhancement pass; default precise","type":"string","enum":["precise","creative"]}},"required":["video"],"$schema":"http://json-schema.org/draft-07/schema#"}},{"name":"use_brand","description":"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).","write_action":false,"price_micros":0,"input_schema":{"type":"object","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"}},"required":["brand"],"$schema":"http://json-schema.org/draft-07/schema#"}}],"scan":{"score":83,"grade":"B","scanned_at":"2026-09-18T00:15:17.348Z","report":{"scannerVersion":"0.1.2","scannedAt":"2026-09-18T00:15:17.240Z","components":{"code":{"score":25,"max":25,"notes":["11 source files scanned"]},"reliability":{"score":20,"max":20,"notes":["remote reachable in 1024ms"]},"poisoning":{"score":13,"max":15,"notes":["175 tool descriptions checked"]},"auth":{"score":3,"max":15,"notes":["open endpoint exposes 70 write-action tools with no auth"]},"maintenance":{"score":15,"max":15,"notes":["last push 0 days ago"]},"identity":{"score":7,"max":10,"notes":["registry namespace matches repository owner"]}},"findings":[{"id":"auth.open-write","severity":"high","component":"auth","title":"Write-action tools reachable without authentication"},{"id":"poison.long-description","severity":"low","component":"poisoning","title":"Unusually long tool description (over 2,000 characters)","evidence":"tool schedule_post: …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.…"}],"inputs":{"probes":[{"url":"https://app.hermoso.ai/mcp?src=registry","reachable":true,"authRequired":false,"latencyMs":1024,"serverInfo":{"name":"hermoso","version":"1.0.0"}}],"packages":[{"registryType":"npm","identifier":"hermoso","version":"0.1.252","found":true,"license":"MIT","hasInstallScripts":false,"dependencyCount":1,"publishedAt":"2026-09-17T20:49:06.390Z","repositoryUrl":"git+https://github.com/hermoso-ai/hermoso.git","weeklyDownloads":4348}],"repo":{"found":true,"owner":"hermoso-ai","repo":"hermoso","archived":false,"pushedAt":"2026-09-17T20:51:15Z","stars":0,"openIssues":1,"ownerType":"Organization","ownerCreatedAt":"2026-07-02T13:58:44Z","license":"MIT"}}}},"grade_history":[{"kind":"restore","fromGrade":"C","toGrade":"B","reason":"score 83: Write-action tools reachable without authentication; Unusually long tool description (over 2,000 characters)","createdAt":"2026-09-18T00:15:58.456Z"}]}