Hermoso
OfficialHermoso is a full-stack AI marketing platform enabling AI agents to run end-to-end marketing operations: research competitors, generate ads, publish to social channels, and manage paid campaigns across multiple networks.
Ad Research & Competitive Intelligence
Search Meta, Google, LinkedIn ad libraries and organic social (TikTok, Instagram, YouTube, Reddit, Threads)
Find competitors by domain and pull their running ads
Tear down competitor strategies into playbooks, mine customer angles from reviews/social
Analyze video ads (structure, transcripts) and fetch long-tail social data via ScrapeCreators
Creative Generation
Plan ad concepts with copy variants and storyboards
Render finished video ads via Studio pipeline, generate raw images, videos, talking avatars, voiceovers, and text with multiple AI models
Create native-feel template ads (iMessage, ChatGPT chat, carousels, etc.)
Fan out variations and score/rank ads
Post-Production
Reframe, upscale, dub videos; swap voices; add film grain/DR proof pills
Fix individual beats, stitch multi-scene videos, trim, speed adjustments, motion recast
Remix competitor static ads into on-brand versions
Publishing & Scheduling
Publish to Facebook, Instagram, Threads, TikTok, YouTube, X, LinkedIn (profiles/pages), Pinterest, Google Business Profile
Schedule, list, and cancel posts across channels
Upload local or external files for use in posts
Ad Campaign Management
Full management for Meta, Google Ads, LinkedIn Ads, Pinterest Ads, Microsoft Advertising, ChatGPT Ads
Create, list, report, update budgets/status, delete campaigns (created paused, spend changes confirm-gated)
Upload assets, pull performance insights (spend, impressions, CTR, CPC, conversions)
File & Document Management
CRUD files on Google Drive, OneDrive; read/write Google Sheets and Docs
Upload files to public URLs; browse workspace asset library; fetch render job details
Workspace & Account
Manage brand workspaces, team members, roles, connectors, skills, AI employees
Handle billing: check credits, buy packs, upgrade plans, auto-reload
Store workspace memory, lock product photos, check ad policy compliance
Allows publishing to Facebook Pages, managing posts, listing Pages and ad accounts, and creating/managing Facebook ad campaigns through Meta's APIs.
Provides Google Ads campaign management (list, report, create, budget, status) and access to the Google Ads Transparency Library for ad research.
Enables creating and appending to Google Docs documents.
Offers full CRUD for Google Drive files and folders, including saving assets and organizing them.
Supports creating spreadsheets, appending rows, and reading data from Google Sheets.
Allows publishing images and Reels to a linked Instagram business account, and searching Instagram Reels for creative research.
Provides management of Meta advertising campaigns across Meta's ad platform, including campaign/ad set/ad creation, budget and status controls, and performance insights.
Allows managing ad campaigns on OpenAI's Advertiser API (ChatGPT Ads), including listing, creating, reporting, and adjusting campaigns.
Enables posting to Pinterest boards and managing Pinterest Ads campaigns.
Supports searching Reddit posts to mine customer language, pain points, and trends for ad research.
Allows posting to Threads and searching Threads posts for social trend and voice research.
Provides publishing to TikTok and searching TikTok videos for hooks, trends, and creative inspiration.
Allows posting videos to YouTube, updating video metadata, retrieving video insights and comments, and searching YouTube for content research.
This server has a remotely hosted endpoint. Open its connector listing for connection details, authentication requirements, and setup instructions:
Hermoso: AI marketing agent and AI ad generator for Claude, ChatGPT and Cursor (MCP server, CLI and skills)
The AI marketing agent with an AI ad generator built in, run from any AI agent: Claude Code, Claude.ai, Cursor, Codex, or your own scripts. Research the ads already winning in a market, generate image & video ads (your real product composited in, copy + CTA included), publish them to your own social channels, and build & manage the ad campaigns behind them, all over MCP tools, a CLI, or installable Claude skills.
Start free: 160+ free credits, no card. No markup on models. Sign up at app.hermoso.ai; plans at hermoso.ai/pricing.
What it does
Meta Ads MCP server. Build, read and manage Facebook and Instagram campaigns, ad sets, ads, audiences and insights from your agent, preview an ad per placement, and estimate reach before you spend. New campaigns are created paused.
Google Ads MCP. Search and Performance Max campaigns, ad groups, keywords and keyword ideas, assets, conversion actions, budgets and reports.
TikTok Ads MCP, and the same campaign tools for LinkedIn Ads, Reddit Ads, Pinterest Ads, Snapchat Ads, Microsoft Advertising, X Ads, Apple Ads, ChatGPT Ads and Amazon Ads.
AI ad generator API. Image, video and UGC avatar ads with your real product, copy and CTA, from
render_ad,generate_imageandgenerate_video, the CLI, or the REST API at/v1(OpenAPI).Ad spy. Search the Meta, Google and LinkedIn ad libraries and organic TikTok, Instagram, YouTube, Reddit and Threads, and turn a competitor's longest-running ads into angles you can use.
Posting. Post and schedule to your own social channels, then read each post's results. The channel list is under What it connects to below.
Related MCP server: Ad Library MCP
Set up in ChatGPT, Claude, Grok Bot or a coding agent
ChatGPT: one click. Add to ChatGPT opens Hermoso in ChatGPT's app
directory. Press Install plugin and sign in with your Hermoso account, no key needed. Then
open a new ChatGPT chat with your first message typed, or paste it yourself:
Hermoso, set up my brand from my website and make my first ad
Claude (claude.ai, Claude Desktop): one click. Add to Claude opens Claude's Add custom connector dialog with Hermoso already filled in. Press Continue, choose Sign in now if Claude asks about Authentication, then sign in with your Hermoso account.
Grok Bot, Meta Muse, Claude Code, Cursor, Codex and any other agent that can read a link and run a command: one line, no key. Paste this into a new chat and the agent reads hermoso.ai/SKILL.md, which gives each host its own steps, signs you in and makes your first 3 ad ideas:
Follow https://hermoso.ai/SKILL.md to set up Hermoso for me, then make 3 ad ideas for my brand and show me the best one as an image.Grok Bot and Muse each run on their own cloud computer, so they set Hermoso up there and send you a sign-in link to approve. OpenClaw and Hermes usually run on a server you chat with on Telegram, Discord or WhatsApp, so there is no browser for the sign-in. Paste the same line there: the agent sends you a sign-in link with a short code, you approve it on your phone, and it carries on. No key needed.
Grok Bot's full setup prompt, the same steps spelled out for a Bot that does not open the link:
Set up Hermoso for me so I can research ads, find creators, generate images and videos, and publish from here.
1. Sign me in from your command line: run `npx -y hermoso auth login --device --no-wait`. It prints a link and a code. Send me both, wait until I say I approved, then run `npx -y hermoso auth login --device --resume`.
2. Add an MCP server of type stdio (a command), not a URL. Command: `npx -y hermoso mcp`. It uses the sign-in from step 1, so it needs no key.
3. Then run one real tool call: list my brands.The full setup prompt, the same setup spelled out for an agent that cannot open a link (this is Claude Code's install line; each agent's own is in the app under MCP & CLI):
Set up Hermoso for me. It is an AI marketing tool (hermoso.ai) that researches ads, makes image and video ads and posts to my social accounts.
1. Install it by running: claude plugin marketplace add hermoso-ai/hermoso && claude plugin install hermoso@hermoso
If the new skills only load after a restart, tell me, and use npx meanwhile.
2. Sign me in by running: npx -y hermoso auth login
It opens my browser and I will approve the connection there. If this machine has no browser, run npx -y hermoso auth login --device --no-wait instead: send me the link and the code it prints, and once I say I approved, run npx -y hermoso auth login --device --resume.
3. Once I am signed in, do one small task to show it works: tell me my Hermoso credit balance and which profile is saved.
4. Then set up my brand from my website and make my first ad.Claude by hand: Customize → Connectors → Add → Add custom connector, paste the URL below, choose Sign in now under Authentication, then Add and Connect. On a Team or Enterprise plan an Owner adds it for the organization first.
https://app.hermoso.ai/mcpChatGPT by hand: turn on Developer mode once (Settings → Security and login), then Plugins → + → Create app →
Create MCP App. Paste https://app.hermoso.ai/mcp as the Server URL, choose OAuth, leave the advanced OAuth
settings empty, and press Create.
Claude Code:
claude plugin marketplace add hermoso-ai/hermoso && claude plugin install hermoso@hermosoCursor:
npx skills add hermoso-ai/hermoso -a cursor && npx -y hermoso auth loginOr add the MCP server to Cursor's mcp.json after npx -y hermoso auth login:
{ "mcpServers": { "hermoso": { "command": "npx", "args": ["-y", "hermoso", "mcp"] } } }Codex, Gemini CLI, Grok and the rest are in Install in one command.
Examples
Ask in your own words. The agent picks the tools:
"Pull the longest-running Meta ads for allbirds.com and tell me the three angles they keep paying for."
"Make a 15-second UGC video ad for our product in 9:16, with a voiceover and captions."
"Make four static ads for the new collection, one per Instagram placement."
"Build a Meta Ads campaign for this video with the daily budget I give you, leave it paused, and show me the preview."
"Compare last week's Google Ads and Meta Ads results and tell me what to pause."
"Schedule this video to TikTok, Instagram Reels and YouTube Shorts for Tuesday at 9am."
1584 tools. tools/list is always the authoritative set; hermoso_capabilities (free) returns the live model
catalog with exact per-render credit costs plus the full capability map.
No markup on models on Starter, Pro and Studio. Stop overpaying markups on AI models. Plans: hermoso.ai/pricing.
A Chrome extension too. Hermoso: save and clone ads saves any ad to your swipefile in one click, clones it for your brand, and pulls any company's ads from its website.
Most of it costs nothing. Publishing and scheduling posts, building and managing paid campaigns, analytics
and insights, comments and DMs, connectors, profiles and team seats cost no credits on any plan, with no
per-post fee and no seat pricing. The Free plan includes 5 posts a month on up to 3 platforms; every paid plan posts without a limit and runs autopilot. Basic ($19.99 a month) is Autopilot, plus unlimited posting and scheduling with no monthly credits: it includes the same 160+ free credits as the Free plan, and monthly credits start on Starter. Credits are spent only on running an AI model (image, video,
voice, text, planning, post-production) and on Ad Spy research, and posting an ad you already rendered is never a
second charge. The one exception is X (Twitter), where posting and reads bill credits per call because X
charges per API request (hermoso_credits prints the exact credits per X post).
What it connects to. Ad platforms: Meta, Google Ads, TikTok Ads, LinkedIn Ads, Reddit Ads, X Ads, Pinterest Ads, Snapchat Ads, Microsoft Advertising, Apple Search Ads, ChatGPT Ads, AppLovin Ads and Amazon Ads, plus product feeds in Google Merchant Center. Publishing and scheduling — eighteen channels: Facebook, Instagram, Threads, TikTok, YouTube, X, LinkedIn, Pinterest, Bluesky, Telegram, WordPress, the Shopify blog, Webflow, Wix, Discord, Slack, Whop and Google Business Profile. Messaging: WhatsApp (you message a person, so it is not a nineteenth publishing channel) and DM automations on Instagram, Facebook Pages and Messenger, and X (a keyword comment, a DM, a story reply or an ig.me / m.me link gets an automatic reply). Ad research: the Meta, Google and LinkedIn ad libraries plus organic TikTok, Instagram, YouTube, Threads and Reddit. Analytics: Google Analytics 4, Google Search Console and every connected platform's own post and campaign insights. Files: Google Drive, Sheets, Docs and OneDrive.
It is not all-or-nothing. Research, creation, publishing/scheduling and ads management are four independent
areas — no tool requires that you used another one first. Publish or schedule creative you already have and
generate nothing here (upload_file turns any local or external file into a URL every publish, schedule and
ad-build tool accepts); build and read campaigns on your own ad accounts with your own creative; research
competitors with no brand drafted and no channel connected; or generate a file with nothing connected at all and
just download it. Use the one piece you need, or all of it together.
Install in one command
This repo is a plugin marketplace, a Gemini CLI extension and a skills package at once, so a coding agent takes
Hermoso in one line. Every install brings the same seven skills (hermoso-research, hermoso-generate,
hermoso-ad-from-brand, hermoso-product-photoshoot, hermoso-marketing, hermoso-edit-timeline,
hermoso-launch-app), and the skills drive the hermoso
CLI through npx. No
tool list is loaded into your session: a CLI command costs nothing until it runs, and it reaches every tool.
The first time, your agent runs npx -y hermoso auth login, which opens a browser to sign in.
Claude Code:
claude plugin marketplace add hermoso-ai/hermoso && claude plugin install hermoso@hermosoInside a session the same thing is /plugin marketplace add hermoso-ai/hermoso then /plugin install hermoso@hermoso.
Codex CLI (it reads the same marketplace file):
codex plugin marketplace add hermoso-ai/hermoso && codex plugin add hermoso@hermosoGemini CLI:
gemini extensions install https://github.com/hermoso-ai/hermosoGrok (xAI) comes in three shapes, and each one connects differently:
grok.com and the Grok apps take the hosted connector: open Plugins → Connectors → New Connector → Custom (or go straight to grok.com/connectors), paste
https://app.hermoso.ai/mcpand sign in with your Hermoso account.Grok Bot: send it the one line above. It signs in from its own cloud computer with
npx -y hermoso auth login --device(a link and a short code you approve on your phone), then runs the stdio servernpx -y hermoso mcp. No key.Grok Build, xAI's terminal agent, runs a local MCP server. Sign in once, then add it:
npx -y hermoso auth login grok mcp add hermoso -- npx -y hermoso mcp
Cursor, OpenCode, GitHub Copilot, Windsurf and about 75 more agents, through the open skills installer:
npx skills add hermoso-ai/hermosoIt asks which agents to install into; -a opencode (or cursor, github-copilot, windsurf) picks one, and
--skill hermoso-research installs a single skill. VS Code agent plugins can also take this repo whole: run
Chat: Install Plugin From Source and paste https://github.com/hermoso-ai/hermoso.
ChatGPT and Claude.ai run in a browser and cannot run a CLI, so they use the hosted connector instead (see
below). The ChatGPT desktop app and ChatGPT workspace admins can also read this repo's
.claude-plugin/marketplace.json, which installs the skills.
No browser on the machine (a server, an SSH session)? npx -y hermoso auth login notices and shows a link and a short
code instead: open the link on your phone and approve. --device asks for it directly; an agent that relays the link
over chat runs npx -y hermoso auth login --device --no-wait (prints the link and exits), then
npx -y hermoso auth login --device --resume once you have approved. Only if nothing can open a link: create a key in
the app under MCP & CLI and run npx -y hermoso auth login --token <key>.
On a server, a CI job or an agent gateway that calls Hermoso many times a day, install it once
(npm i -g hermoso) and call hermoso directly. npx asks the npm registry about the package on every run,
and a busy machine can be rate-limited by npm. If the CLI ever says an HTTP error "did not come from Hermoso",
something on your side (a proxy, a firewall or the gateway) refused the request before it reached us.
Which surface should your agent use?
Two shapes, and the right one is decided by what your client can do, not by which we prefer.
Your client | Use | Why |
Runs in a browser: Claude.ai, ChatGPT, Claude Desktop | the hosted connector | It cannot spawn a local process, so a URL is the only shape it has. Nothing to install, no key to paste, and the full toolset arrives with your saved brand context. This is the right answer for these clients, not a lesser one. |
Can run a shell: Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, Hermes, your own scripts | the one-command install above, or the CLI itself ( | A tool manifest is loaded into every session whether or not a tool is called. A shell command costs nothing until it runs, and it reaches every tool rather than the default roster. |
The CLI answers the questions a tool manifest would, on demand and only when asked:
npx -y hermoso tools --search reddit # every matching tool, name + one line
npx -y hermoso tools plan_ad # one tool's full argument schema
npx -y hermoso call plan_ad --json '{"product":"…"}' # run ittools and tools <name> read a registry bundled in the package (no key, no network, no sign-in), so an agent
can browse the entire product before anyone signs in. Only call spends, and only that needs
hermoso auth login once.
Want the tools in your coding agent's own list as well? That is the MCP server, and it is optional. One
hermoso auth login covers the CLI and lets claude mcp add hermoso -- npx -y hermoso mcp pick the key up with
no env block, so the agent can reach for a native tool when it wants structured results and shell out when it
wants breadth. It costs context in every session, so add it when a session settles into one area and makes many
calls there; enable_tools({groups:['ads']}) then turns campaign management on in a single free call.
Your agent can sign itself up
An agent with no Hermoso account can provision one, get its own key, and be rendering ads in the same session. No human at a browser, no ticket, no waiting.
# 1. Start a signup. This call takes no credential, because the credential is what it creates.
curl -sX POST https://app.hermoso.ai/v1/signup \
-H 'content-type: application/json' \
-d '{"plan":"pro","period":"mo","email":"you@yourcompany.com"}'
# -> { "id": "cs_...", "checkout_url": "https://checkout.stripe.com/...", "claim_token": "hsc_...", "email": { "address": "you@yourcompany.com", "verified": false } }
# email = the human behind the account. A verification link goes there; the account works before it is clicked.
# It is a contact mailbox only, never a sign-in. GET /v1/account/email reports the state; POST /v1/account/email/resend re-sends or changes it.
# 2. Pay at checkout_url. Store claim_token first: it is returned only in that response.
# 3. Claim it. Poll until status is "ready".
curl -sX POST https://app.hermoso.ai/v1/signup/cs_.../claim \
-H 'content-type: application/json' \
-d '{"claim_token":"hsc_..."}'
# -> { "status": "ready", "api_key": "hmk_...", "credits": 3000 }That hmk_ key is the same credential everything else on this page takes: /v1, the MCP server, the CLI. Point
your client at it and the full surface is open.
Paying is something a browser-capable agent can already do itself. Checkout is Stripe's own hosted page, so
Claude in Chrome and clients like it complete it unattended today. Everything else is a one-click handoff: send
checkout_url to whoever holds the card. The same shape covers you later, once you are running: buy_credits
and upgrade_plan mint a ready-to-pay link for more credits or a bigger plan, and billing_status reads the
balance any time.
An agent with its own payment credential can pay with no human at all. POST /api/billing/machine-payment
with {"packId": "pack-1k"} answers HTTP 402 carrying a WWW-Authenticate: Payment challenge (Stripe, through the
Machine Payments Protocol); pay the challenge and retry, and the same credit pack lands on the same balance.
GET /api/billing/config lists the packs under machinePayments. Same packs, same prices, no per-call billing.
The agentic path takes a paid plan. Any of them. The free plan is there for a person signing up at app.hermoso.ai, and asking for it here returns a refusal that says so. Nothing is created until the payment completes, so an unpaid signup leaves no account behind and charges nothing.
One thing still wants a person, and it is worth knowing up front. Connecting a social or ad account means an
OAuth consent screen, and a consent screen cannot be completed headlessly on any platform. list_connectors
shows what is already connected and what is not. Everything else runs with no browser at all: research,
generation, publishing to a channel that is already connected, campaign builds, reporting.
Full request and response shapes, plus every other endpoint, are in the OpenAPI document at app.hermoso.ai/openapi.json, served live from the same table that mounts the routes.
Instant: the hosted Claude.ai connector
Add to Claude opens Claude with the connector already filled in: press Continue, sign in with your Hermoso account, and you are done.
By hand: paste https://app.hermoso.ai/mcp?src=readme into Claude → Customize → Connectors → Add → Add custom connector,
press Continue, choose Sign in now under Authentication (Claude's detector pre-selects "No sign-in" because our
discovery handshake is open, and with that your first request comes back "Authentication required"), press Add and
Connect, approve with your Hermoso account, and you are done: the full toolset with your saved brand context, billed to your plan.
Quickstart for Claude Code (one command)
Get an account at app.hermoso.ai. The free tier is included; plans and credits are the same ones the web Studio uses. Or skip the browser entirely and let your agent sign itself up on a paid plan with
POST /v1/signup(above).Install the plugin. It adds the seven Hermoso skills, which drive the
hermosoCLI throughnpx:
claude plugin marketplace add hermoso-ai/hermoso && claude plugin install hermoso@hermoso Already inside a session? /plugin marketplace add hermoso-ai/hermoso, then /plugin install hermoso@hermoso.
Codex, Gemini CLI and the rest are in Install in one command.
3. Sign in once. npx -y hermoso auth login opens your browser; your agent also runs it by itself the first
time it needs Hermoso. On a machine with no browser it shows a link and a short code to approve on your phone
(npx -y hermoso auth login --device). Only if nothing can open a link, use npx -y hermoso auth login --token hmk_…
with a key from the MCP & CLI tab, under Terminal & API keys (https://app.hermoso.ai/?tab=api-keys).
4. Ask for what you want, in your normal prompts. Claude Code picks the Hermoso skill for the job and runs the
commands. You type none of them.
Rather install the CLI by hand? npm install -g hermoso puts the same hermoso command on your PATH, and the
skills use it when it is there.
The hosted URL works in Claude Code too, but the plugin is the lighter path there because it loads no tool list
into your sessions. If you want the connector: claude mcp add --transport http hermoso "https://app.hermoso.ai/mcp?src=readme",
and claude mcp list reports ! Needs authentication until you run claude mcp login hermoso once and approve in
your browser (--no-browser prints the link on a headless machine). Measured against Claude Code 2.1.282 on 2026-09-25.
Your agent now has the full studio with your profile's context: the brand details, products, logos and
learned memory you set up in the web app apply automatically (get_brand shows what's saved; omit brand in
plan_ad/plan_variations to use it). Renders bill your Hermoso credits, at the same prices as the Studio. Only AI model runs and Ad Spy research spend credits; publishing, scheduling, ads management and analytics cost no credits on any plan (posting to X and reading X data are the one per-call exception, managing X ads is free). The Free plan includes 5 posts a month on up to 3 platforms; every paid plan posts without a limit and runs autopilot. Basic ($19.99 a month) is Autopilot, plus unlimited posting and scheduling with no monthly credits: it includes the same 160+ free credits as the Free plan, and monthly credits start on Starter.
1. MCP server (stdio), optional in a coding agent
hermoso mcp runs a stdio MCP server exposing the full toolset, for a client that wants Hermoso's tools in its own
list. The published hermoso package means no clone: npx -y hermoso mcp fetches and runs it. Sign in once with
the CLI and no key goes into any client config, because hermoso mcp reads the bearer hermoso auth login stored:
npm install -g hermoso && hermoso auth login && claude mcp add hermoso -- npx -y hermoso mcpOn a machine with no browser, skip the sign-in and pass the key to the client instead:
claude mcp add hermoso -e HERMOSO_TOKEN=hmk_… -- npx -y hermoso mcpCursor / Codex: sign in the same way, then add to mcp.json (Codex uses the TOML equivalent). Drop the env
block entirely if you signed in above; it is there for CI, where the process cannot read your home directory:
{ "mcpServers": { "hermoso": { "command": "npx", "args": ["-y", "hermoso", "mcp"],
"env": { "HERMOSO_API_BASE": "https://app.hermoso.ai", "HERMOSO_TOKEN": "<your token>" } } } }Then ask your agent: “Generate an image ad with Hermoso.”
What the 1584 tools cover
Ad spy / research — find_competitors, competitor_teardown, pull_competitor_ads, research_ads; the
Meta / Google / LinkedIn ad libraries (search_meta_ads, search_google_ads, search_linkedin_ads); organic
social (search_tiktok, search_instagram, search_youtube, search_reddit, search_threads);
fetch_social_data, mine_angles, analyze_video, check_ad_policy, list_skills / get_skill. Leads:
find_leads (companies and public posts showing a buying signal now, billed per lookup under a hard maxCredits)
then find_company_contacts (the public business address from the company website, free).
Create — draft_brand → plan_ad → render_ad (the Studio quality pipeline: composited text, clean speech,
music, brand end card), or generate_image / generate_video / generate_avatar (UGC creators + lip-sync).
The workspace's saved cast is reusable: list_creators returns every saved creator with their portrait url,
save_creator adds one, delete_creator drops one — re-pass a portrait to generate_avatar / generate_video /
recast_motion and the SAME person stars in every ad, instead of a new face each render.
Also make_template_ad (native HTML ad formats), make_explainer, product_sizzle, make_thumbnail,
clone_static, recast_motion, reframe_video, upscale_video, dub_video, change_voice, finish_video,
fix_beat, stitch_video, clip_video, post_edit, plus plan_variations + score_ad to fan out and rank.
Length is yours to set: pass durationSeconds to plan_ad and the storyboard is authored to it — a length
that fits one clip of the render model renders as a single continuous take, longer is stitched from acts (on a
15s-clip model, 40s = 15+15+10), never time-compressed. What fits one clip is the model's own maximum, not a fixed
number: most video models cap a clip at 15 seconds and the longest-clip one takes 30 seconds in one unbroken
take with native synchronized audio. hermoso_capabilities is the live list — durations, resolutions and the
exact credit cost of every tier — and naming that model in model is how you get it, since an unnamed render is
routed by a narrower auto-pool.
Ads Studio (make_static_ads): pick products and a count and get a batch of finished static ads in one call,
each a different selling angle and a different layout, with your real product photo and logo laid on. The product
catalog it draws from (list_products, add_product, refresh_products, update_product, remove_product) is a
cache of each product's live page, so names, photos and prices come from the page itself.
Swap a person into any video (recast_hook, recast_motion): keep the scene, the cuts and the sound and change
who is on screen, using your own photo, a saved creator or an AI person (in the web Studio you can describe a presenter in words).
Real faces from your own photos need a paid plan; AI people work on every plan.
Raw model playground — the full catalog (30+ image / video / voice / writing models, each with its exact
per-render credit cost) with no ad framing: generate_image / generate_video with useBrand:false,
generate_voice, generate_text. The image default is Nano Banana 2.1.
Publish to your own channels — eighteen of them: Facebook, Instagram and Threads (post_to_meta), TikTok
(post_to_tiktok), YouTube (post_to_youtube + update_youtube_video, youtube_video_insights, comments
read/reply), X (post_to_x, x_post_metrics, x_post_insights, x_mentions, list_x_dms, send_x_dm),
LinkedIn profile and company Pages (post_to_linkedin, post_to_linkedin_page), Pinterest
(post_to_pinterest + boards), Bluesky (post_to_bluesky, delete_bluesky_post, bluesky_post_metrics, plus
list_bluesky_convos / read_bluesky_dm / send_bluesky_dm) and Telegram (post_to_telegram,
delete_telegram_message, list_telegram_chats), WordPress (post_to_wordpress, update_wordpress_post,
delete_wordpress_post, list_wordpress_posts), the Shopify blog (post_to_shopify_blog, update_shopify_article,
delete_shopify_article), Webflow (post_to_webflow, update_webflow_item, delete_webflow_item), Wix (post_to_wix,
update_wix_post, delete_wix_post), Discord and Slack announcements (post_to_discord, edit_discord_message,
delete_discord_message, post_to_slack), Whop (post_to_whop, edit_whop_post, delete_whop_post, get_whop_post,
list_whop_destinations) and Google Business Profile (below). schedule_post / list_scheduled / cancel_scheduled give
you one content calendar over exactly that set. upload_file brings in any external or local media, not just
Hermoso renders.
X posting bills credits per API call (X charges per request); a post containing a link costs 13× one without.
Google Business Profile is the panel a business shows on Google Search and Maps. post_to_google_business
publishes a Post with text, optionally one photo, and a call-to-action button (Google takes no video in Posts, so
a schedule with only a video is refused for that channel); list_google_business_posts and
delete_google_business_post manage what is showing. list_google_business_reviews finds the reviews with no
answer yet and reply_to_google_business_review answers one as the business. google_business_insights reports
search and Maps impressions, calls, website clicks and direction requests, and google_business_search_keywords
the words people searched to find the listing. list_business_locations, get_business_location and
update_business_location read and edit the listing itself: hours, phone, website, description, categories.
Business Profile Q&A is not offered: Google retired it on 2025-11-03.
Message customers on WhatsApp — messaging, not a twelfth publishing channel: you message a person, and
nothing here posts to a feed. list_whatsapp_accounts finds the Business Account and its
numbers, list_whatsapp_templates / create_whatsapp_template / delete_whatsapp_template manage the templates
Meta reviews, and send_whatsapp_message sends one — confirm-gated, because it reaches a real phone and Meta
bills the business for the conversation. Two limits that are permanent facts about Meta's API rather than
anything pending: Hermoso does not receive WhatsApp webhooks, so there is no message history to read — it is
not an inbox surface and list_inbox does not cover it — and outside the 24-hour window that opens when the
customer messages first, WhatsApp accepts an APPROVED template and nothing else.
Automate Instagram DMs — save_instagram_dm_automation sets up a rule that answers people for the brand: a
comment with a keyword on one post, the next post or any post gets a private reply, and a DM, a story reply or an
ig.me link gets an answer, with optional link buttons, a public comment reply, a follow gate and a dry run.
test_instagram_dm_automation shows exactly what a sample comment or DM would send without sending it, and
list_instagram_dm_automations / delete_instagram_dm_automation read each rule's stats and send log or remove
it. Each person gets one reply per post, Meta allows a private reply within 7 days of the comment, and no AI runs
on the send path, so it costs no credits.
Automate DMs on Facebook and X too — save_dm_automation (with test_dm_automation, list_dm_automations and
delete_dm_automation) takes a channel: instagram, facebook (a keyword comment on a Page post or an ad gets a
private reply in Messenger; a Messenger keyword or an m.me link gets an answer) or x (a keyword @mention or a reply
under your post gets a public reply; a DM keyword gets a DM back). X only allows an automated DM after the person has
DMed you, and a DM saying STOP opts that person out. Facebook is free like Instagram. X bills us per call, so an X
automation is charged in credits for every mention, reply or DM X delivers plus each reply or DM sent, and running out
of credits stops its X rules.
Autopilot posting (set_post_refill, get_post_refill, run_post_refill): say how often, where and what
about ("2 posts a day on Instagram and Bluesky about our slow-morning routine, let me review first") and Hermoso
makes new posts from your brand and fills your calendar. Pick review first (each batch waits for your approval,
edit or redo) or post automatically (straight onto the schedule, still pullable). It follows the notes you leave and
writes from what has worked on each channel. Credits are used only when a post is made.
Run the ads — full campaign trees, built paused and read back before anything is reported, with every spend
change confirm-gated, on thirteen platforms: Meta, Google Ads, Amazon Ads (Sponsored Products and Sponsored Brands), LinkedIn Ads, Reddit Ads,
Pinterest Ads, Microsoft Advertising, ChatGPT Ads (OpenAI's Advertiser API), X Ads, TikTok Ads,
Snapchat Ads, Apple Ads (Apple Search Ads on the App Store) and AppLovin Ads (reporting and the website
pixel on the keys every account has; campaign building once AppLovin enables Campaign Management API access on the
account, and server-side conversion events with the Conversion API key AppLovin issues on request). Each has list + report + create + budget/status tools
(e.g. list_google_ads_campaigns, google_ads_report, create_google_ads_campaign, set_google_ads_budget,
set_google_ads_status). Snapchat needs one extra step the others do not: an ad points at a CREATIVE, and every
Snapchat creative must carry a Public Profile id — build it with upload_snapchat_ads_creative.
Feed the shopping surfaces — Google Merchant Center is the catalog a retail Performance Max or Shopping
campaign advertises (create_google_ads_performance_max_campaign takes a merchantCenterId), and you manage it
from here: accounts and account status, data sources, product upsert / update / delete, per-region inventory,
quota, merchant_report for product-level performance, notifications and conversion sources, plus the disapproval
loop — list_merchant_issues says what is wrong and merchant_issue_help returns Google's own documented fix.
Promotions need the merchant's own enrolment in Google's promotions program; without it Google refuses that
sub-API outright. Microsoft Merchant Center is covered on the same shape (stores, catalogs, products, issues)
for Bing Shopping.
Measure what the ads achieved — Google Analytics 4 closes the loop. Every other connector here reports what an
ad cost; this is the one that reports what it did. analytics_report breaks sessions, users, conversions and
revenue down by channel, source/medium, campaign, landing page, country, device or date, so the campaign Hermoso
built and the revenue it drove sit in one conversation. analytics_realtime shows who is on the site right now.
Start at list_analytics_properties — the tools take a numeric property id, not the G-XXXXXXXXX Measurement ID
from your tracking snippet, and this is what resolves one from the other. It writes as well as reads:
create_analytics_key_event marks an event GA4 already collects as a key event — which is what makes it importable
into Google Ads as a conversion — and create_analytics_custom_dimension registers an event parameter so reports
can break down by it, with list_analytics_definitions showing what the property already measures. It signs in
with the same Google account as Google Ads, YouTube and Drive, but it is its own connection.
GA4 only — the API has no Universal Analytics surface. A custom dimension can be archived but never deleted, and a
property holds 50 event-scoped ones.
Files — Google Drive CRUD (save_to_drive, list_drive_files, update_drive_file, delete_drive_file,
create_drive_folder), Google Sheets (create_sheet, append_to_sheet, read_sheet), Google Docs
(create_doc, append_to_doc), and OneDrive (save_to_onedrive + full CRUD).
Workspace & account — profiles (list_brands, create_brand, use_brand, update_brand,
delete_brand; one account holds many profiles, each a brand, a client, a creator or a personal workspace, so an agency runs every client through here), memory
(remember, forget, list_memory), custom skills (save_skill, get_skill, list_skills,
delete_skill — the one library, which absorbed the old AI-Employee personas), team (list_team, invite_member, remove_member,
set_role), settings (get_settings, update_settings — including the language every ad, script and plan
is written in), connectors (list_connectors, list_connector_accounts, set_connector_accounts,
disconnect_connector), and billing (hermoso_credits, billing_status, buy_credits, upgrade_plan,
set_auto_reload), plus list_jobs / get_job for async renders.
Connector accounts are picked, not guessed. One person often administers several Facebook Pages, Google Ads customers or LinkedIn company Pages. Only the accounts ticked for a profile are usable — enforced server-side, and an empty selection shares nothing. Linking a new account is the one step that is not headless (it is an OAuth consent screen, so the user does it in the app).
Render jobs queue server-side and poll to completion, returning a served URL.
2. CLI: the context-free path for terminal agents
bin/hermoso.mjs exposes the full MCP toolset as subprocess commands, so an agent can shell out instead of carrying a
fat tool manifest.
npm install -g hermoso # installs `hermoso`
hermoso capabilities # valid model ids + costs (run first)
hermoso create --brand "YourBrand" --product "your best-selling product" --format image
hermoso generate image --prompt "…" --ref ./product.png --wait
hermoso generate video --prompt "…" --duration 8 --wait
hermoso competitors yourbrand.com
hermoso research "Liquid Death’s longest-running ads"Add --json to any command for machine output.
Those shortcuts are the common path, not the limit. Every tool the MCP server has is reachable here too, including the ad-campaign and analytics groups a connector leaves out of its default roster:
hermoso tools # every tool, grouped, name + one line
hermoso tools --group ads --search reddit # narrow it
hermoso tools create_meta_campaign # that tool's full argument schema
hermoso call create_meta_campaign --json '{"name":"…"}' # run it
hermoso create_meta_campaign --name "…" # same thing, shortercall goes through the same handler, the same argument validation and the same confirm/spend gates the MCP
server uses, so there is no second implementation to drift. tools and tools <name> read a registry bundled in
the package, so they need no key, no network and no sign-in.
3. Skills: what a coding agent installs
skills/ holds seven installable skills:
Skill | What it does |
| Find competitors, pull their real running ads, surface the hooks worth copying |
| A prompt to a finished image, video, avatar clip or stitched cut |
| A brand or domain to one on-brand ad, concept and copy included |
| A real product photo composited into studio, lifestyle or hero scenes |
| The whole loop: research, create, publish and schedule, paid campaigns, measure |
| The manual for composing any video edit or transition with |
| Launch and market an app or site you just built: brand, launch ads, a week of scheduled posts |
They are what every one-command install at the top of this page adds, in Claude Code, Codex, Gemini CLI and
through npx skills add. From a clone, copying works too:
cp -r skills/* ~/.claude/skills/Then invoke /hermoso-ad-from-brand an ad for yourbrand.com, our hero product.
Ask for it in your own words
The skills pick themselves. These are whole prompts, not commands:
Find my top 5 competitors for [product + URL], pull their best Meta and TikTok ads from the last 90 days, and tell me the 3 hooks and 2 formats worth stealing, with the evidence.
Make this week's ads for [brand]: two hooks in two formats, one UGC and one product visual, 9:16. Score them and policy check them before I ship.
Here is a competitor ad: [link]. Break down why it works, then rebuild the structure with my product, my branding and a fresh hook.
Fill my social queue for the next 7 days across Instagram, TikTok, X and LinkedIn, repurposed from my best post, with per-channel captions.
Take last week's winner and build a $20/day test campaign on Meta and TikTok, three ad sets, one angle each. Leave it paused and read the tree back so I can check it.
Pull last month's campaign performance across every platform. Which two creatives won, why, and what should next month's brief say?
Configuration
Env | Meaning |
| The Hermoso API origin (default |
| Bearer agent key ( |
| Profile id, for accounts with multiple profiles |
| Only for a profile another account shared with you (a team workspace): the owning account id. Set it together with |
mcp/http.mjs is the hosted remote-connector transport (paste-a-URL into Claude.ai → Connectors). It ships in
this repo for transparency and refuses to mount without authenticated identity — no anonymous spend, ever.
License
MIT © Hermoso
Available Tools
216 toolsadd_subtitlesAdd subtitles to a videoAInspect
Burn subtitles into ANY video and get the .srt too; nothing is cut or re-rendered. Set textStyle only when the user describes a look (default: white sentence case, thin outline, bottom). Timed by the spoken words (up to 5 words a line); auto:'sentences' times per sentence. Only when asked, textStyle 'highlight' (or a highlightColor) lights the word being said, timed word by word. Or pass cues to burn your own lines exactly, untranscribed (reel-style phrases, stage directions). burn:false returns only the .srt. Takes a video file or URL, a Vimeo-style page, or a TikTok / Reel / X post link (not YouTube: YouTube does not let us download videos, so upload the file). No speech is refused and refunded. Runs in the background and lands in the Library.
Inputs: video (required), auto, burn, cues, +6 more.
analyze_videoAnalyze videoAInspect
A video ad's structure: verbatim transcript (voiceover + on-screen text), beat list, duration and sampled frame times; study a reference before remixing it. ~A transcription call.
Inputs: url (required), words, frames, anchors, +3 more.
append_to_docAppend text to a Google DocAInspect
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). Optional dropdown:{title, options:[2-50], selected} appends a Google Docs dropdown chip after the text — e.g. text "Status: " + dropdown {title:"Status", options:["Draft","In review","Approved"]} gives a brief a status the team can click to change; the chip is confirmed by reading the doc back. Set it later with update_doc dropdowns.
Inputs: documentId (required), text, dropdown.
append_to_notion_pageAdd to a Notion pageAInspect
Add to the END of an existing Notion page (pageId or its link, from list_notion_pages): markdown content, a swipefileCollection, or includeSchedule:true. Nothing already on the page changes. Free.
Inputs: pageId (required), content, includeSchedule, swipefileCollection.
append_to_sheetAppend rows to a Google SheetAInspect
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.
Inputs: rows (required), spreadsheetId (required), range.
backfill_postsImport a channel’s past postsAIdempotentInspect
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 has 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.
Inputs: channel (required), limit, cursor, confirm, +1 more.
billing_statusBilling statusARead-onlyIdempotentInspect
Show this account's billing at a glance: current plan (quote plan.priceUsd per plan.period), 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. plan.memberRate: media models at cost + 10%; plan.legacy: an older plan kept at its price. posting: this month's posting allowance ("N of 5 posts used this month" on Free, unlimited on every paid plan).
Inputs: no named parameters.
buy_creditsBuy creditsAInspect
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 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.
Inputs: pack, confirm, quote_token.
call_toolRun any Hermoso tool by nameADestructiveInspect
Run a Hermoso tool that is not in this session's starting list (paid campaigns, analytics, channel admin and more), using the exact name and args that find_tools returned. Use find_tools first. It runs that one tool on this Hermoso account, and the tool's own rules still apply: a spend or a delete still asks for confirm. Use it on hosts that keep the tool list they fetched at connect time (claude.ai, ChatGPT), where enable_tools cannot add tools mid-conversation. Arguments are checked against the tool's schema; a mistake comes back with the expected parameters. A tool for an account this workspace has not connected answers with the link to connect it.
Inputs: name (required), args, context, revision.
cancel_scheduledCancel a scheduled postADestructiveIdempotentInspect
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).
Inputs: id (required), brand.
change_voiceChange narrator voiceAInspect
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.
Inputs: video (required), voice, get_cost, idempotency_key, +1 more.
check_ad_policyCheck ad policyAInspect
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.
Inputs: copy (required), claims, category, get_cost, +3 more.
check_videoCheck a videoAInspect
Check a finished video for named, mechanical issues, ONLY when the user asks (never after every render, and it never re-renders): loudness vs a target (default -14 LUFS) and true peak, black and frozen stretches, captions or text outside the platform-safe band, text running off the frame. Optional assertions about named elements: appearsBy {element, bySec}, before {a, b}, staysInFrame {element}, keepsMoving {maxStaticSec}. Each issue comes with a Fix line. The loudness, black and frozen checks are free; the on-screen text and element read is a small paid frame read (frames:false skips it).
Inputs: url (required), frames, get_cost, assertions, +3 more.
clear_sheet_rangeClear a range in a Google SheetADestructiveIdempotentInspect
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.
Inputs: range (required), confirm, sheetUrl, confirmCells, +1 more.
click_to_adPlan a video ad from a product linkAInspect
Paste a product page link (Shopify, Amazon or any store page) and get a creator-style video ad planned for that product. Hermoso reads the page (name, photos, what it says about the product, price), saves the product to the brand's catalog, checks the page's real product photo and pins it to this ad (the brand's saved default photo is not changed), then plans the ad. A store that hides its page from servers is read in a real browser; failing that the name comes from the link and the photo from a search, and the reply says so. Nothing renders here: show the user the concept, then call render_ad with the returned creative (dryRun:true first for the exact price). Works with or without a saved brand.
Inputs: url (required), say, style, get_cost, +4 more.
clip_videoClip a long videoAInspect
Cut ONE long video into several RANKED, ready-to-post short clips (podcast, webinar, interview, talk, long ad cut -> Reels/Shorts/TikTok). Transcribes with timestamps, picks the strongest SELF-CONTAINED moments, then cuts + reframes each with ffmpeg — no video model renders anything, so it is fast and cheap. 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. SUBTITLES ARE BURNED IN BY DEFAULT (white sentence case timed by the spoken words, thin black outline, bottom safe band, no box) because short-form is watched on mute; captions:false for clean footage. TIMING IS APPROXIMATE (per-sentence, not word-level); never promise frame-accurate sync. Full rules: get_instructions({topic:'clip_video'}).
Inputs: video (required), count, captions, get_cost, +3 more.
clone_staticClone a static adAInspect
Use this when the user wants their own version of a static (image) ad they like, a competitor's or any reference. It rebuilds it on-brand: SAME layout, composition and energy, but the user's product, brand colours, logo and voice, with every trace of the source brand removed. Pass imageUrl = the static ad image to clone. Uses the saved brand (brandId picks another profile, like use_brand). IMAGES ONLY — for a video ad use clone_video with its link, then render_ad. Bills as one image generation.
Inputs: imageUrl (required), brandId, get_cost, idempotency_key, +1 more.
clone_videoClone a video for your brandAInspect
Remake a video you like FOR THIS BRAND from its link — a TikTok, Instagram Reel, Facebook video or reel, X post, or a direct video file URL. YouTube does not let us download videos, so a YouTube link is refused up front and nothing is charged; the user downloads it themselves and uploads the file (upload_file). 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 120s) 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. For a ready short-form FORMAT instead of a link (a Reel / TikTok structure with its own captions and a Comment-keyword close), use make_short. Reuse a style: save_video_preset.
Inputs: url (required), brand, changes, product, +5 more.
collect_post_metricsRead how the recorded posts performedAIdempotentInspect
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.
Inputs: max, brand, remeasure, includeMetered.
competitor_teardownCompetitor teardownAInspect
Use this when the user asks how a competitor advertises, what its ad strategy is, or where the openings against it are. It turns the competitor's ads into a 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?}. Pass ads (raw ad objects from a prior pull_competitor_ads / search_meta_ads call) to tear down exactly those, or omit it and this pulls the competitor's longest-running Meta ads first. Tailored to the saved brand. Spends credits (free when you pass ads).
Inputs: competitor (required), ads, get_cost, language, +2 more.
connect_connectorConnect a paste-a-key accountADestructiveIdempotentInspect
Connect an account that links with a KEY rather than a sign-in screen, from here, with no browser: AppLovin Ads, Twilio, Vapi, Retell AI, ElevenLabs, Sendblue, LoopMessage, Telnyx, Stripe, Intercom, Mailchimp, Any mailbox, Klaviyo, Vercel, ChatGPT Ads, Apple Ads, Bluesky, Telegram, Bing Webmaster Tools, PostHog, Mixpanel, Amplitude, LINE, WooCommerce, WordPress, Webflow, Wix, Slack, Discord, Webhook. Gmail and Google Workspace too: provider "gmail", fields { email, password } with an APP PASSWORD (detect_mailbox_settings gives the steps); it sends and reads replies. 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 (Connectors, or the one-click link https://app.hermoso.ai/?connect=) 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: applovin_ads {reportKey, eventKey, apiKey, capiKey, accountId} · twilio {accountSid*, authToken, apiKeySid, apiKeySecret} · vapi {apiKey*} · retell {apiKey*} · elevenlabs {apiKey*} · sendblue {apiKeyId*, apiSecret*} · loopmessage {apiKey*, sender} · telnyx {apiKey*, publicKey} · stripe {apiKey*} · intercom {accessToken*, region} · mailchimp {apiKey*, server} · smtp {email*, password*, preset, username, smtpHost, smtpPort, smtpSecurity, imapHost, imapPort, imapSecurity, fromName} · klaviyo {apiKey*} · vercel {token*, team} · 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} · line {channelAccessToken*, channelSecret*, replaceWebhook} · woocommerce {storeUrl*, consumerKey*, consumerSecret*} · wordpress {siteUrl*, username*, appPassword*} · webflow {token*, siteId, collectionId} · wix {apiKey*, siteId*, memberId} · slack {webhookUrl, announceWebhookUrl} · discord {webhookUrl, announceWebhookUrl} · webhook {webhookUrl*}.
Inputs: provider (required), fields.
contact_supportContact Hermoso supportAInspect
Message Hermoso's human support team for the user: billing, account or sign-in problems, a connector that will not connect, or a question the tools cannot answer. Use the user's words. The team replies by email to the account's address (the result names it). Defects you found: report_bug. Missing capabilities: request_feature. Free.
Inputs: message (required), page.
convert_onedrive_fileConvert a OneDrive file to PDF or JPGAInspect
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.
Inputs: fileId (required), width, format, height.
create_brandCreate a profileAIdempotentInspect
Add a NEW profile (a brand, client, creator or personal workspace) and switch to it. Each has its OWN brand details, memory, swipefile, Library, avatars, skills, playbooks and connectors; nothing leaks between them. Use draft_brand to FILL it and update_brand to edit it. Re-running with the same name returns the existing profile instead of a duplicate. Creating it is free. Drafting a NEW brand into it (draft_brand) needs the credits for its research on the balance, about 100; with fewer, draft_brand refuses before anything runs or is charged and says how many it needs and how many the account has.
Inputs: name (required), activate.
create_docCreate a Google DocAInspect
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 (Connectors > Google Drive — one connection covers Drive, Sheets and Docs).
Inputs: text, title.
create_drive_folderCreate a Drive folderAInspect
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).
Inputs: name (required), parentId.
create_onedrive_folderCreate a OneDrive folderAInspect
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.
Inputs: name (required), parentId.
create_sheetCreate a Google SheetAInspect
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 (Connectors > Google Drive — one connection covers Drive, Sheets and Docs).
Inputs: rows, title.
delete_brandDelete a profileADestructiveIdempotentInspect
PERMANENTLY delete a profile and EVERYTHING in it — brand details, 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 profile was destroyed. The account's FIRST/anchor profile cannot be deleted this way (it holds the workspace's root storage) — that one is replaced from the app.
Inputs: brand (required), confirm, confirmName, confirmConnectors.
delete_creatorDelete a creatorADestructiveIdempotentInspect
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.
Inputs: id (required), brand.
delete_drive_fileDelete a Drive fileADestructiveIdempotentInspect
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.
Inputs: fileId (required), confirm, permanent.
delete_library_itemDelete from LibraryADestructiveIdempotentInspect
PERMANENTLY delete images/videos from this brand's Library: the entry and the stored file. Pass ids (L0… from list_library) or urls. Without confirm it lists what would be deleted; ask the user, then call again with confirm:true. Free.
Inputs: ids, urls, confirm.
delete_linkedin_lead_subscriptionStop a LinkedIn lead webhookADestructiveIdempotentInspect
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.
Inputs: subscriptionId (required), pageId, adAccountId.
delete_onedrive_fileDelete a OneDrive fileADestructiveIdempotentInspect
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.
Inputs: fileId (required), confirm.
delete_playbookDelete a playbookADestructiveIdempotentInspect
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.
Inputs: id (required), brand.
delete_skillDelete a custom skillADestructiveIdempotentInspect
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.
Inputs: id (required), brand.
diagnose_postsWhat to fix next, post by postARead-onlyIdempotentInspect
WHAT TO FIX NEXT, post by post, and the tool that fixes it: post_performance says which hook is AHEAD; this says what is WRONG with a post. 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, to repeat rather than paper over: (1) a post younger than ~24h is TOO EARLY, never a failure; (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, Google Business nothing per post); (3) below 5 measured posts on a channel there is no brand baseline, 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: attribute it as the output does; (4) 'nothing here needs fixing' is a real answer, not a failure to look. Hermoso cannot see conversions for an organic post (no channel reports them against a post id), so the offer rung runs ONLY when the user says they are not converting and you pass converting:false. Print summary verbatim. Read-only, 0 credits.
Inputs: limit, channel, converting.
disconnect_connectorDisconnect a connected accountADestructiveIdempotentInspect
Disconnect a third-party account from this workspace (Meta, Google Ads, Google Drive/Sheets/Docs, YouTube, TikTok, LinkedIn, X, Reddit Ads, 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. IT NEVER REVOKES THE GRANT AT THE PROVIDER: the authorisation stays in place, so the same account keeps working in any other brand it is connected to, until the user removes Hermoso in that provider's own settings. The unconfirmed call names where to do that (list_connectors carries revokesAtProvider:"local") — relay it rather than promising a revoke. WITHOUT account, EVERY account on that connector is removed (pass account to remove just one). Removing a mailbox stops the emails still waiting to go from it: its sequences pause and say why. RECONNECTING IS THE USER'S JOB: a sign-in account needs their browser (the provider's consent screen), so an agent cannot undo this. Name the provider to the user, then call with confirm:true. Use list_connectors for the exact provider ids.
Inputs: provider (required), account, confirm.
draft_brandDraft profileADestructiveInspect
Use this when the user gives a website, a description or a social handle to set up their brand or creator profile. It fills in the profile: its name, products, logo and summary, saved as the brand profile when none is saved yet. On an account with NO saved brand one call does it all: it saves the brand and reads its product photos (no second call with confirmed:true). Check the business it returns against what you know about the user and go straight on to the ad unless you have a real reason to think it is a different business. Next, for an image ad call generate_image directly (plan_ad is for a video or for concepts to choose from). 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): if the returned name or summary is clearly not the business the user named, re-draft with the correct domain or a description.
Inputs: save, domain, platform, confirmed, +2 more.
dub_videoDub videoAInspect
Localize a finished video into another language WITHOUT re-rendering it: each spoken line is said where it was said, in a native voice, lip-synced, background kept. Pass the video and the language; the script is read off the source (script only overrides it). Paid by length; dryRun quotes. Returns the localized video URL.
Inputs: video (required), language (required), voice, dryRun, +4 more.
duplicate_scheduledDuplicate a scheduled postADestructiveInspect
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.
Inputs: id (required), at, link, brand, +18 more.
edit_imageEdit an imageAInspect
EDIT an existing image in place with a plain-language instruction and keep everything else: 'make the headline bigger', 'add our logo bottom right', 'swap the background for a kitchen', 'remove the person on the left', 'erase all the text'. Pass image (URL, Library item, upload_file URL or local path) and instruction. The same edit the web Studio's Edit runs: composition, aspect ratio, people and every untouched line of text stay as they are; the saved brand's real name and website are pinned so an added line never invents one, and the brand's real logo FILE is put on when the instruction asks for the logo (never redrawn by the model): an ask only about the logo ('the logo is wrong', 'make the logo bigger'; or logo:true, any language) runs no image model. Set removal:true when the edit STRIPS text, branding or an object, so nothing branded is put back. When the saved brand has a product photo and the ad shows that product, the photo rides with the edit and the product's label is read and checked against it: re-printed from the photo only when it came out wrong (the check alone is charged when it is right; one small extra charge finds the product first). fixLabel:false turns that off. For a precise region, pass mask (see generate_image). One image edit's credits; returns the new image URL. For a new image from a prompt use generate_image; to rebuild a competitor's ad for your brand use clone_static.
Inputs: image (required), instruction (required), logo, mask, +9 more.
edit_videoEdit a video clipAInspect
SWAP AN OBJECT IN A VIDEO ('replace the cup with our can' + the product photo as elements) or EDIT an existing clip from a plain instruction (video-to-video): the motion, timing, framing and cut stay, the named thing changes. 'change only the mug to red', 'make it nighttime', 'restyle it as claymation'. Your words are wrapped so the model keeps everything else identical, changes only what you named and repeats that lock; lighting is kept unless the change needs new light (set lighting to force either); literal:true sends your words as written. One change per call holds best. previewFirstFrame:true edits ONE still first (one image edit; previewAt picks the second) and quotes the clip; nothing else runs until you call again, ideally with previewStill. The reply scores how well the shot held outside the change (free) and flags an edit that touched more than asked. NOT for cuts/trims/end cards (post_edit), a new video (generate_video / render_ad), translating what is SPOKEN (dub_video) or a saved creator's face (recast_motion). Translating or rewriting the on-screen words of a video laid out from a design (a template ad, a custom design) is textChanges with every line at once: one re-make of the design, about 2 credits. Best on 3-15s clips.
Inputs: video (required), instruction (required), engine, literal, +13 more.
enable_toolsTurn on more Hermoso toolsAIdempotentInspect
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 across every ad platform is most of the total schema weight. 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.
Inputs: groups (required).
error_detailError detailARead-onlyIdempotentInspect
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.
Inputs: fingerprint (required).
export_schedule_to_notionExport the schedule to NotionAInspect
Export the posting schedule to a Notion database, one row per post: date, channels, caption, media link and status. Creates a new database (under parentPageId, or private in the workspace) or writes into an existing one (databaseId), matching its columns by name. historyDays adds posts already published. Up to 100 rows per run; the answer says if more were left. Free.
Inputs: title, databaseId, historyDays, dataSourceId, +1 more.
export_swipefile_deckSwipefile to Google SlidesAInspect
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. 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 (Connectors > Google Drive — one connection covers Drive, Sheets, Docs and Slides).
Inputs: limit, title, collection.
fetch_app_screensFetch App Store screensAIdempotentInspect
Pull an APP brand's REAL store screenshots (Google Play or App Store) 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'. A store link or package id goes in storeUrl and is read exactly; else pass appName (defaults to the saved brand's name). A web app with no store listing gets the screenshots of the product its OWN website shows (pictures the site labels as its interface). Call it before telling the user you have no screenshots of their app. FREE — a keyless store lookup or one read of the brand's homepage. 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.
Inputs: appName, brandId, storeUrl.
fetch_assetFetch assetARead-onlyIdempotentInspect
Resolve a generated asset reference (a /generated/… path or any URL) to a clickable absolute URL + a direct download URL.
Inputs: url (required), name.
fetch_social_dataFetch social dataAInspect
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.
Inputs: path (required), params, get_cost, idempotency_key, +1 more.
find_competitorsFind competitorsAInspect
Use this when the user asks who a brand's competitors are, or for similar brands to learn from, and gives its website. It finds competitor / similar / adjacent brands from the domain (an AI model grounded by web search). mode=competitors (default, excludes the searched company), inspiration (best relevant ads incl. it), or company. Bills one model call, no ad-data charge; free during a new account's first brand setup.
Inputs: domain (required), mode.
find_creatorsFind the creators already winning in a nicheAInspect
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). marketplace:true also searches Instagram’s creator marketplace (Meta’s own creator directory: followers, badges, marketplace email) for the same niche and returns those rows beside the ranked list.
Inputs: niche (required), limit, enrich, queries, +7 more.
find_soundFind a soundAInspect
A sound for an edit by name ('the FAAAA sound'), by the moment ('bad news reaction') or by link (TikTok sound, meme-sound page, post, audio file): a durable mp3 and where it starts and lands. Named/described sounds come from what TikTok uses now; pick takes another candidate. A sound that does not exist yet is generate_sfx.
Inputs: url, pick, query, get_cost, +2 more.
find_toolsFind a Hermoso tool by name or taskARead-onlyIdempotentInspect
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 you found with call_tool({name, args}): search, then run, two calls for any tool in the product. 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.
Inputs: group, limit, query, onlyHealthy.
finish_videoFinish videoAInspect
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, billed for its compute only. 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.
Inputs: videoUrl (required), sub, grain, pills, +6 more.
fix_beatFix a video beatAInspect
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. A FINISHED VIDEO-BLOCKS FILM (make_explainer's explainer or faceless channel; get_job says it is editable) is edited ONE BLOCK at a time instead: pass job (its job id) and block (1-based) or atSeconds, with prompt for a different shot and/or line for new narration words. Only that block is re-rendered and/or re-read; every other block, take, the music and the captions are the film's own and stay aligned. It is priced as that block alone and charged exactly what it quotes (dryRun). The original film is kept; a new film comes back, and it can be edited again. Feedback maps to one named move, never a re-render: quieter/louder (music db, audio_gain), faster/slower (speed; slower = zooms and pans at 0.7x), tighten (trim), retime (to a word anchor), recut (order, in-out points), regrade (timeline exposure/contrast/saturation keys).
Inputs: job, line, block, dryRun, +10 more.
forgetForget a memoryADestructiveIdempotentInspect
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.
Inputs: id (required), brand.
format_sheetFormat a Google SheetADestructiveIdempotentInspect
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.
Inputs: tab, sheetUrl, autoResize, boldHeader, +2 more.
generate_avatarGenerate talking avatarAInspect
ANIMATE A PHOTO so it talks: the presenter in image says script word for word, a separate voice lip-synced onto the still. Use it ONLY when the user asks for an animated photo / talking photo / lip-sync look by name; for any other talk-to-camera or spokesperson ask use generate_video with speak (the person filmed saying it, which reads as real footage). About 1-3 min, holds the pose steady, 480p/720p. The per-second credit price is in hermoso_capabilities (avatarEngines); dryRun:true returns this exact job's hold without rendering. Blocks until done where the host allows, else returns a job id to poll with get_job. Requires canAvatar. Spends credits; a refusal before rendering costs nothing.
Inputs: image (required), script (required), seed, voice, +8 more.
generate_imageGenerate ad imageAInspect
Use this when the user asks for an image ad, ad creative, product photo or social post graphic for their business or product, or an ANIMATED GIF (format gif) or SVG file (format svg). It renders a finished image on a real image model, on their saved brand (product photos, logo), and returns a URL ready to post. For a video, use render_ad. The saved brand’s product photo is used automatically (see get_brand / list_product_photos), so never ask the user to upload it again. MULTI-BRAND: hydration uses the SAVED brand; for a different brand (a fresh draft_brand) pass its own productImages/logo as refImages with useBrand:false, or the wrong product lands in the shot. model = a catalog id from hermoso_capabilities (omit for the default). Seconds. Spends credits. Full rules: get_instructions({topic:'generate_image'}).
Inputs: job, raw, mask, model, +16 more.
generate_musicGenerate musicBInspect
RAW music: describe it (genre, mood, instruments, tempo), get an instrumental MP3. No length: a full track at a flat fee (explainerMusicCredits in hermoso_capabilities). With seconds: by the second up to about 38 s. A named model always runs.
Inputs: prompt (required), model, seconds, get_cost, +2 more.
generate_textGenerate textAInspect
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: omit for the default Claude orchestrator. Claude Fable 5.2 runs on paid plans only; on the Free plan it is refused at no charge. Paid (billed at the writing model's token cost, by length).
Inputs: prompt (required), raw, model, get_cost, +2 more.
generate_videoGenerate videoAInspect
Use this when the user asks for a video clip, b-roll or a shot from a description, or names a video model. For a finished video ad, Reel, TikTok ad or UGC video for their business, use render_ad. A GIF is generate_image format gif. It renders one continuous clip on a real video model and returns its mp4 URL. A clip runs up to the model’s longest listed duration (the longest takes a multi-beat 30s spot in ONE take with native audio), so never assume an 8–10s cap or stitch what fits one clip; durationSeconds must be one of the model’s durations in hermoso_capabilities. NAME A MODEL in model to get it: an unnamed render uses a narrower auto-pool. 1–3 min. refImage anchors the first frame; ttsScript adds a voiceover. AUDIO IS NOT FREE BY DEFAULT: a clip with no audio of its own gets a music bed composed and CHARGED on top (see musicMood and audio), which can cost as much as a cheap draft clip. refVideo (a clip URL) EDITS that clip instead, keeping its canvas and length. RAW MODEL ACCESS: by default small guards are added (label safety with no reference image, a negative prompt where the model takes one, reference lines) and hex colours become names; 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 (blocked on the Starter plan).
Inputs: raw, loop, audio, model, +26 more.
generate_voiceGenerate voiceover or dialogueAInspect
RAW speech as an MP3: one voice reading a script (text), or a DIALOGUE of two or more people (lines), each in their own voice. Not for adding audio to a video (render_ad and generate_video voice their own spots; change_voice re-voices a finished clip). ONE VOICE: text + engine (default 'seed-audio'; also 'eleven-v4', 'minimax-speech', 'kokoro'…) + voice, a preset from that engine (hermoso_capabilities -> voice engines); a name the engine does not have is REFUSED for free with its real list, and a few engines make their own voice (the reply says which voice spoke). DIALOGUE: lines [{speaker, voice, text}] in speaking order. Each speaker keeps ONE voice, no two speakers share one, a speaker with no voice gets one nobody has; up to 10 voices and 10,000 characters, refused for free past that. Default engine: the dialogue model (Eleven v3 Dialogue, voices Aria, George, Sarah, Roger, Laura, Charlie, Callum, River, Liam, Charlotte, Alice, Matilda, Will, Jessica, Eric, Chris, Brian, Daniel, Lily, Bill, or an ElevenLabs voice id; '[laughs]'-style cues work); or name any voice engine (e.g. 'eleven-v4') to read each line on it and join them in order. dryRun:true returns the exact credits and makes nothing; the price quoted is the charge. Paid, priced by characters (hermoso_capabilities lists credits per 1,000).
Inputs: text, lines, voice, dryRun, +4 more.
get_brandGet saved profileARead-onlyIdempotentInspect
What Hermoso ALREADY KNOWS for the active profile: the same saved profile (products, logos, palette, fonts, 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.
Inputs: brand.
get_drive_fileGet a Drive file’s detailsARead-onlyIdempotentInspect
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.
Inputs: fileId (required).
get_instructionsRead Hermoso's full instructionsARead-onlyIdempotentInspect
Free. Hermoso's instructions on demand: a topic (areas, instagram, capabilities, roster, safety, credits, setup, all) for the rest of the session instructions, any tool's name for its FULL rules, or "paid-calls" for get_cost, expected_credits, idempotency_key, revision and context.
Inputs: topic (required).
get_jobGet render jobARead-onlyIdempotentInspect
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).
Inputs: id (required).
get_linkedin_leadRead one LinkedIn leadARead-onlyIdempotentInspect
One LinkedIn lead by id (from list_linkedin_leads), with every answer named by field. Personal data — show, never republish. Read-only, free.
Inputs: leadId (required), pageId, adAccountId.
get_onedrive_fileGet a OneDrive file’s detailsARead-onlyIdempotentInspect
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.
Inputs: fileId (required).
get_post_refillAutopilot posting statusARead-onlyIdempotentInspect
Show AUTOPILOT POSTING (autoposting, the posting refill) for this profile — "is autopilot on?", "what is waiting for review?": whether it is on, its mode (review = each batch of fresh posts waits as drafts for approval; auto = fresh posts are scheduled straight away), WHICH CHANNELS it posts to with each one’s posts per day and posting times, roughly what it costs a day, when it next runs, how many posts are queued, the DRAFTS waiting for approval (id, time, channels, caption, the new image or video), and the notes it learned from reviews. It also names the channels that CANNOT be posted to and why. On the Free plan, paidOnly is true and note explains the status. Read-only, free.
Inputs: no named parameters.
get_settingsRead app settingsARead-onlyIdempotentInspect
Read this account's app settings — the LANGUAGE Hermoso writes ads and copy in (chat replies follow the language the user writes in), the app appearance (theme), which Hermoso emails are on (tips, product news, credit and plan notices, competitor watch, autopilot reviews, weekly posts, and the all-emails switch), and ZERO CONTENT RETENTION (on = Hermoso keeps ids and metadata only, never message, post, prompt or transcript text once delivered). Same settings as the web app's Settings pane. Read-only, free.
Inputs: no named parameters.
get_skillGet skillARead-onlyIdempotentInspect
Load a bundled skill’s full SKILL.md workflow instructions by name (from list_skills), or a built-in in-app skill by its id (e.g. youtube_script, retention_skeleton). Follow the loaded instructions to run that workflow with the other tools. Read-only, free.
Inputs: name (required).
headline_variantsHeadline variants of a static adAInspect
Turn ONE finished static ad into several copies that differ ONLY in the headline, for an A/B test: same picture, product, layout, colours and every other line. Pass image, and either headlines (your own, up to 10) or count (default 5, max 10) to have distinct angles written for you in the saved brand's voice (never inventing numbers, prices, ratings or claims the ad or brand does not state); brief steers what to test. The ad's text is read first (3 credits), then one image edit per headline; each output is proofread and flagged (textCheck) if the rendered words do not match, never silently re-rendered. When the saved brand has a product photo and the ad shows that product, the photo rides with the edit and the product's label is read and checked against it: re-printed from the photo only when it came out wrong (the check alone is charged when it is right; one small extra charge finds the product first). fixLabel:false turns that off. The whole batch is priced before anything runs. Returns each headline, its angle and its image URL.
Inputs: image (required), brief, count, fixLabel, +4 more.
hermoso_capabilitiesHermoso models, options and credit costsARead-onlyIdempotentInspect
Probe what this Hermoso account can do RIGHT NOW: available image/video model ids + their credit costs (estimates: a render is charged its actual cost), aspect ratios, video durations, the recipe ids, and the canEdit/canAvatar flags. Call it when you need a specific model id, a credit 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.
Inputs: no named parameters.
hermoso_creditsCredit balanceARead-onlyIdempotentInspect
Return the credit balance, recent priced calls with their credits, 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 cost no credits on any plan (X is the single per-call exception; xCost gives its exact credits per post, with and without a link). Check before kicking off paid generation; answer "does posting cost credits?" with NO. HOW MANY posts is set by the plan, not credits: the Free plan includes 5 posts a month on up to 3 channels, and a post counts once however many channels it goes to (posting says how many are used); every paid plan posts without a limit and runs autopilot (Basic $19.99/mo: Autopilot, plus unlimited posting and scheduling, no monthly credits; it includes the same 160+ free credits as the Free plan, and monthly credits start on Starter). Starter, Pro and Studio: media models at cost + 10% (memberRate); Basic and Free pay standard prices.
Inputs: no named parameters.
hook_variantsNew opening hooks for a videoAInspect
HOOK MULTIPLIER: give ONE finished video ad N NEW OPENING HOOKS, N complete versions to A/B test. Pass the video's FILE URL (a render, job result, list_library or upload_file). 1-5 versions, default 3. COST: quoteOnly:true returns the exact credits free: state that first. A paid planning read (planCredits) runs next, then each planned version bills like fix_beat for the hook's seconds. dryRun:true pays for that read; pass its plan back to render exactly those. Returns ONE JOB PER VERSION; call get_job on each until done, never describe a version before its URL arrives. Full rules: get_instructions({topic:'hook_variants'}).
Inputs: video (required), plan, count, hooks, +10 more.
import_from_cloudImport a Drive / OneDrive folder into the LibraryAInspect
Pull the files in a Google Drive or OneDrive FOLDER into this profile'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) 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. Picking a FOLDER hands over the folder alone, not the files in it, so if a folder comes back empty the reply carries a link that opens the picker inside it, where the user selects every file at once (Cmd+A / Ctrl+A); give them that link. 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.
Inputs: provider (required), limit, folderId.
insert_sceneInsert a new scene into a videoAInspect
INSERT a newly generated scene into a clip you already have: the video plays up to startTime, the new scene (5 to 13 seconds) plays, then the original picks up again at resumeTime. Use for a product close-up, a reaction, a reveal or a missing beat in the middle of an ad without re-rendering the rest. resumeTime = startTime keeps every second of the original; a later resumeTime also cuts the footage in between. Describe the scene in prompt and/or attach up to 4 reference pictures (refImages) or 1 reference clip (refVideos). Clips up to 60 seconds; both times between 1.625 and 60 seconds. Paid render (billed per second of NEW scene); returns the whole video's URL.
Inputs: video (required), startTime (required), resumeTime (required), prompt, +7 more.
instagram_posting_holdSee or resume a held Instagram accountADestructiveIdempotentInspect
See or lift the HOLD on an Instagram account's scheduled posts. When Meta refuses two posts in a row from an Instagram account with its spam restriction (code 4/2207051, "We restrict certain activity to protect our community"), Hermoso holds that account's scheduled Instagram posts instead of sending them into the restriction: they stay queued and nothing is posted. action:"status" (default) says whether posting is held, since when, and how many posts wait. action:"resume" lifts the hold and releases the waiting posts (ones whose time passed go out 30 minutes apart). Resume only after the user says the account holder has checked Account Status in the Instagram app. Reconnecting Instagram or a successful Instagram post also lifts it. Free.
Inputs: brand, action, account.
invite_memberInvite a teammateADestructiveInspect
Invite someone to this profile 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.
Inputs: email (required), role, confirm.
leave_connectorRemove my own account from a shared connectionADestructiveIdempotentInspect
On a connector that several teammates can contribute their OWN account to (see list_connectors — the row reports multiContributor), remove YOURS from this profile: 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 removes the whole connection for everyone on this profile, and only the person who created the connection may call it.
Inputs: provider (required).
list_brandsList profilesARead-onlyIdempotentInspect
List every profile on this account (id + name; a profile is a brand, a creator or a personal workspace) and which one this connection acts on, PLUS any profile another account shared with you. Call this, then use_brand to switch; a SHARED profile switches the same way (pass its name or the profile id printed here). If a profile looks empty when the app shows it full, you are acting on a different one: call this first. Read-only, free.
Inputs: no named parameters.
list_business_locationsList Google business listingsARead-onlyIdempotentInspect
List the Google Business Profile listings SHARED WITH THIS PROFILE — 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 profile. 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 (Connectors > Google Business Profile).
Inputs: no named parameters.
list_connector_accountsList a connector’s accountsARead-onlyIdempotentInspect
Show every identity a connected account can act as, and which ones this PROFILE 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, pinterest, instagram, meta, google_ads, linkedin, pinterest_ads, linkedin_ads, reddit_ads, apple_ads, amazon_ads, microsoft_ads, google_business, google_analytics, snapchat_ads, x_ads, tiktok_ads, google_tag_manager, google_search_console, bing_webmaster. Read-only, free.
Inputs: provider (required).
list_connectorsList connectorsARead-onlyIdempotentInspect
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 Connectors. Read-only, free.
Inputs: no named parameters.
list_creatorsList saved creatorsARead-onlyIdempotentInspect
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.
Inputs: limit, gender.
list_drive_filesList Google Drive filesARead-onlyIdempotentInspect
List the Google Drive files & folders Hermoso can reach: the ones it created plus any the user picked with the Google file picker in the app (drive.file, never their whole Drive). This is how you find a picked file's id. Filter by query (name contains …), folderId, or onlyFolders:true; paginate with pageToken. Read-only. A FOLDER: picking a folder hands over the folder alone, not its files, so a folder can list empty or partly; the reply then carries pickUrl, an app link that opens the picker inside that folder (Cmd+A / Ctrl+A selects every file and subfolder). Give the user that exact link, then list again. recursive:true walks every subfolder Hermoso can see (each row has its path) and reports picked files whose folder it cannot see.
Inputs: query, folderId, pageSize, pageToken, +3 more.
list_elementsList saved elementsBRead-onlyIdempotentInspect
Saved people, places and products, each with an @name. FREE. An @name in an image or video prompt or an ad brief ("@Sarah in @Kitchen") uses that saved picture as the reference.
Inputs: kind.
list_errorsList errors users hitARead-onlyIdempotentInspect
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.
Inputs: kind, limit, since, surface.
list_hooksThe hook + setting libraries, and which hooks are workingARead-onlyIdempotentInspect
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.
Inputs: tier, channel, category, authentic.
list_jobsList render jobsARead-onlyIdempotentInspect
List the most recent render jobs + how many are currently running, so you can report on or resume in-flight work.
Inputs: no named parameters.
list_libraryList libraryARead-onlyIdempotentInspect
This workspace's Library: every Studio image/video and upload, newest first. Each row: a served URL (fetch_asset gives a download link), its id (L0, L1…, which plan_ad and render_ad inserts take), a TITLE (headline, concept or file name), kind, a video's length, pixel size, model and age. An ad named by its headline ("the Afternoon fix ad"): pass query. To SEE what an image shows, view_images. Free, read-only.
Inputs: kind, limit, query, uploads.
list_linkedin_lead_eventsLinkedIn lead events received in real timeARead-onlyIdempotentInspect
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.
Inputs: limit.
list_linkedin_lead_formsList LinkedIn lead gen formsARead-onlyIdempotentInspect
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 …). Make a new one with create_linkedin_lead_form; edit or archive one with update_linkedin_lead_form. If it answers that the connection must be reconnected, say exactly that: the lead-sync permission is granted at authorise time. Read-only, free.
Inputs: pageId, adAccountId.
list_linkedin_leadsList LinkedIn leads (form responses)ARead-onlyIdempotentInspect
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.
Inputs: limit, since, start, until, +6 more.
list_linkedin_lead_subscriptionsList LinkedIn lead webhooksBRead-onlyIdempotentInspect
The lead notification webhooks registered on a LinkedIn Page or ad account, with the id delete_linkedin_lead_subscription takes. Read-only, free.
Inputs: pageId, leadType, adAccountId.
list_linkedin_pagesList the LinkedIn company Pages this account administersARead-onlyIdempotentInspect
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.
Inputs: no named parameters.
list_memoryList memoryARead-onlyIdempotentInspect
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.
Inputs: limit, category.
list_meta_pagesList Meta pages & ad accountsARead-onlyIdempotentInspect
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 (Connectors > Meta); returns a connect hint if not.
Inputs: no named parameters.
list_meta_postsList the Page’s / Instagram account’s own postsARead-onlyIdempotentInspect
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. 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.
Inputs: brand, limit, cursor, pageId, +5 more.
list_notion_pagesList Notion pagesARead-onlyIdempotentInspect
Find the Notion pages and databases the user shared with Hermoso, by title, newest edited first. Gives the page id that save_to_notion, append_to_notion_page and read_notion_page take, or the database id to save rows into. Read-only, free. Needs Notion connected (Connectors > Notion).
Inputs: type, limit, query, cursor.
list_onedrive_filesList OneDrive filesARead-onlyIdempotentInspect
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.
Inputs: query, folderId, pageSize, pageToken, +1 more.
list_pinterest_boardsList Pinterest boardsARead-onlyIdempotentInspect
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 (Connectors > Pinterest).
Inputs: account, privacy.
list_playbooksList playbooksARead-onlyIdempotentInspect
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.
Inputs: full, limit.
list_product_photosList product photosAIdempotentInspect
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 + the product it shows (the shop's own title when one is on file). These are already saved: never ask the user to upload them again. Call it before set_product_image to see the existing photos you can reuse. Reads YOUR saved brand (pass brandId to target a specific profile — that switches this key's active profile like use_brand).
Inputs: brandId.
list_published_postsList what this brand has publishedARead-onlyIdempotentInspect
List every post Hermoso has recorded publishing for this brand, newest first, across all channels — channel, permalink, caption, format, the HOOK and SUBJECT it was written to, and its measured engagement. The WHOLE history, no cap: pass the reply's nextCursor as cursor for older posts. Each row says how it was recorded: 'captured' (written at publish time — the hook is what the author intended) or 'backfilled' (reconstructed from the platform afterwards). A dash for engagement means the platform reported no number — NOT zero. Read-only, 0 credits.
Inputs: brand, limit, cursor, channel.
list_scheduledList scheduled and past postsARead-onlyIdempotentInspect
Use this when the user asks what is scheduled, what already posted, or whether a post went out. 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.
Inputs: id, brand, fired, channel, +1 more.
list_sheet_tabsList the tabs in a Google SheetARead-onlyIdempotentInspect
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.
Inputs: sheetUrl, spreadsheetId.
list_skillsList skillsARead-onlyIdempotentInspect
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.
Inputs: no named parameters.
list_swipefileList the swipefileARead-onlyIdempotentInspect
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.
Inputs: limit, collection.
list_teamList team membersARead-onlyIdempotentInspect
List the members of the current profile — email, role (admin/member) and status. Read-only, free.
Inputs: no named parameters.
list_telegram_chatsFind Telegram chat idsARead-onlyIdempotentInspect
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.
Inputs: limit, account.
list_watch_findingsRead the market radarARead-onlyIdempotentInspect
Read what a brand's MARKET RADAR (set_competitor_watch) has found: each watched brand's new ads, the winners (ads past 30 days running, with a ready brief to make your own version), the trending formats and top posts for its topics, and the ideas to make, plus its state (lastRun, nextRunAt, lastRunOk, paused) and the quote for its next check. Findings marked seed:true are what a brand was already running at its first check, not new launches. Read-only and free; it never runs a check.
Inputs: brand, limit, competitor.
list_whatsapp_accountsWhatsApp Business accounts and numbersARead-onlyIdempotentInspect
The WhatsApp Business Accounts SHARED WITH THIS PROFILE 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 PROFILE ARE REACHABLE. One Meta login often administers WhatsApp for several businesses, so a human ticks which belong to this profile under 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.
Inputs: no named parameters.
localize_adLocalize a static ad into other languagesAInspect
Translate the on-image text of ONE finished static ad into other languages and keep everything else: same picture, layout, typeface, colours, logo and product. Pass image and languages (up to 5, e.g. ["Spanish", "German", "French (Canada)"]). The ad's text is read (3 credits), translated the way a native copywriter in each market would write it (brand and product names, URLs and prices kept as written), then one image edit per language; each output is proofread and flagged (textCheck) if the words do not match, never silently re-rendered. When the saved brand has a product photo and the ad shows that product, the photo rides with the edit and the product's label is read and checked against it: re-printed from the photo only when it came out wrong (the check alone is charged when it is right; one small extra charge finds the product first). fixLabel:false turns that off. Priced before it runs. For a VIDEO use dub_video.
Inputs: image (required), languages (required), fixLabel, get_cost, +2 more.
make_effectRun a one-click effect on a photoAInspect
ONE-CLICK EFFECTS, the same ones as the /tools pages: a photo goes in, a styled picture comes out, and most can then become a 5-second clip. Plush toy, 3D figure, mascot, comic book, pixel game, billboard ad, giant product, bullet time, packshot, outfit swap, headshot, relight and many more. Name no effect for the free list. effect alone: what it takes. effect + images: a free quote; add confirm:true to make the picture. Then effect + still (that picture's URL): a free quote for the clip; confirm:true makes it. describe adds anything of your own. For a look not on the list use generate_image. A real person's photo follows the same likeness rules as every render.
Inputs: text, still, effect, images, +8 more.
make_explainerMake an explainer videoAInspect
AI HOST EPISODE: format 'host_episode' = one presenter talking to camera, the camera changing every piece (frontal, three-quarter, close), the same host and set throughout, native voice, 16:9. It returns a 480p DRAFT; HD (720p) is a SEPARATE call with fromDraft (quote it with dryRun, run it only when the user asks). Otherwise: turn a TOPIC into a finished narrated explainer video, in one of TWO LANES (lane). BURNED ON-SCREEN TEXT IS OFF BY DEFAULT; the film ships clean unless the user asks; captions:true adds held key points and subtitles:true adds subtitles timed to the narration. Takes SEVERAL minutes — one image render per frame; NOT for a short product ad: use render_ad, generate_video or make_template_ad. Full rules: get_instructions({topic:'make_explainer'}).
Inputs: lane, music, style, topic, +24 more.
make_insertMake an insert clipBInspect
A reaction picture (image, or video from videoStart) with its sound, cut to when the sound lands (or seconds): a 1080x1920 clip for post_edit join.
Inputs: sound (required), image, video, seconds, +6 more.
make_motion_filmMake a motion graphics videoAInspect
Use this when the user asks for motion graphics or an animated video: kinetic typography (animated text), a logo animation or intro, a product launch film, an animated social cut. Pick it for 'animated video', 'motion graphics', 'kinetic text', 'text animation', 'logo animation', 'logo intro', 'animated explainer' asks. STEPS: without confirm it is a FREE quote that gives both prices (length, the music's tempo; the spec in structuredContent): say both; preview:true is a 1-credit contact sheet of the still version; confirm:true renders. Only the user's or the brand's words appear: never invent a claim, number or review. Full rules: get_instructions({topic:'make_motion_film'}).
Inputs: help, hook, logo, mood, +22 more.
make_seriesMake a series of faceless short videos (Content Factory)AInspect
CONTENT FACTORY: turn ONE topic into a SERIES of faceless short videos (narration over pictures, no presenter), optionally in the STYLE of a trending reference video. Give topic ("make a video about…"), episodes (1-10, default 1) or your own episodeTitles, durationSeconds (20-120 per episode, default 30) and optionally reference (a TikTok / Reel / Facebook / X link or a video file URL whose look, pacing and opening hook every episode copies, with plain subtitles only if the reference burns its own; never its words or characters). Find a trending reference with search_tiktok / search_instagram / search_youtube when the user wants one. THREE STEPS, ALWAYS IN THIS ORDER: (1) call with no confirm for a FREE quote of the whole series (per episode and total); (2) optionally planOnly:true to see the episode titles and the style card first (a small planning charge); (3) confirm:true (pass the plan from step 2 to reuse it) queues every episode and returns their job ids; poll get_job. To make MORE of a series later, pass its returned plan as moreOf: same style, no episode repeated, the reference not watched again. Each finished episode can be scheduled with this tool again: pass jobIds plus schedule {channels, at, everyHours, timezone} and it books one post per finished episode, spaced everyHours apart (default 24). Captions follow the reference (on if it burns words on screen) unless captions says otherwise.
Inputs: plan, style, topic, voice, +16 more.
make_template_adMake template adAInspect
Use this when the user asks for a quick, low-cost ad or post built from their words and pictures: a slideshow, carousel, iMessage or ChatGPT chat, Notes, kinetic type, myth vs fact, an app tour, or their own HTML design. Rendered from HTML, no AI model, ~30s, billed for its compute only, ready to post. Presets are SHORTCUTS; 'custom' is YOUR OWN design as config.html (+ css), so no layout, type, colour or motion is unsupported. custom: { html, css?, size? ('9:16' default | '4:5' | '1:1' | '16:9' | any 'W:H' | {w,h} px), durationSeconds? (1-60 = VIDEO; CSS/SVG animation and are frame-stepped, scripts stripped), slides?:[{html, css?}] (2-35 = carousel) }; {{logo}} {{brandName}} {{domain}} {{accent}} fill from the brand; images and fonts load by public https URL; notes[] lists what failed to load. YOU write preset copy: short, casual, believable, finished phrases within budget. Preset ids and their fields are listed on config. config.music on a VIDEO: omit for a free library bed matched to its mood when the library is stocked (hermoso_capabilities hasMusic; else only its own sound effects), 'off' for silence, or words (a mood or description) to compose one for a flat fee.
Inputs: config (required), get_cost, idempotency_key, expected_credits.
make_thumbnailMake video thumbnailAInspect
Render a click-driving YOUTUBE / Shorts / Instagram THUMBNAIL or video cover through the full production pipeline (concept, casting, scene, render, tweaks, text), not a bare image prompt. Use it for any "thumbnail", "video cover" or MrBeast-style packaging ask INSTEAD of generate_image. Default: 4 variants at 1K (YouTube shows 1280x720 at most), each billed; 2K or 4K only when the user asks. dryRun:true prices it free. The headline overlay is free. WHO IS IN FRAME — never assume or silently substitute a stranger. A framework with a person and no face photo is refused (nothing charged): ask the user once — themselves (a face photo, identity-locked), a generated person (castGenericPerson:true), or a people-free framework. TEXT — default is a CLEAN render with the headline TYPESET over it (free, legible, correctly spelled): pass headline. bakeText:true only on an explicit ask for words painted INTO the image. ALWAYS check the returned postRenderCheck against the image before presenting it. Full rules: get_instructions({topic:'make_thumbnail'}).
Inputs: font, logo, split, takes, +34 more.
manage_sheet_tabsAdd, rename or delete a sheet tabADestructiveInspect
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.
Inputs: action (required), tab, title, confirm, +4 more.
mine_anglesMine customer anglesAInspect
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 profile — that switches this key's active profile like use_brand). To tear down a COMPETITOR use competitor_teardown instead. YOUR OWN REVIEWS: pass reviews (a list of review texts, or one pasted block: one per line, numbered, blank-line separated, or a CSV with a review column) and/or reviewsUrl (a CSV, TXT or JSON file from upload_file, or a review page; on a local CLI a file path works too). They are first-class evidence: every quote from them is checked word for word against what you sent and labelled 'your reviews', and a quote that is not verbatim is dropped and counted. useOwnReviewsOnly:true mines only your reviews and gathers nothing public. Limits: 300 reviews, 2,000 characters each, 40,000 in total; over that it is refused at no cost, so send fewer or split into batches. Each angle comes back with next: the exact plan_variations and generate_image arguments that turn it into finished statics (one generate_image per angle = statics with distinct angles). Spends credits on the reads and the model's token cost.
Inputs: brandId, reviews, get_cost, reviewsUrl, +3 more.
multiply_adMultiply an adAInspect
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, and the source's own captions and on-screen text stay exactly as they are. ONE JOB PER VARIANT: get_job each until done; never describe a variant before its URL arrives. COST: quoteOnly:true returns the exact credits free: state that first. A paid planning read (planCredits) runs next, then each variant bills perVariantCredits. dryRun:true pays for that read; pass its plan back to render without paying again. No ad: list_winning_ads. New words: rewrite_ad_line. Full rules: get_instructions({topic:'multiply_ad'}).
Inputs: axes, plan, count, notes, +12 more.
onedrive_file_permissionsWho can open a OneDrive fileADestructiveIdempotentInspect
action list (default): every sharing link and person with access to a OneDrive file or folder: link URL, view or edit, scope, expiry, password, whether it is inherited from a parent folder. action remove: revoke one (permissionId from the list); anyone relying on it loses access at once and the link cannot be restored, so WITHOUT confirm:true nothing is removed and you get what would go. An inherited permission is removed on the parent folder, and the owner's own access cannot be removed. Removal is verified by reading the list back. 0 credits. Needs OneDrive connected.
Inputs: fileId (required), action, confirm, permissionId.
plan_adPlan an ad conceptAInspect
Plan an ad: turns a brand and a product or brief into an ad concept, with copy variants (headline, primary text, call to action) and either an image prompt or a timed video storyboard, plus the recipe and the model ids to render with. It renders nothing; pass its output to render_ad, generate_image or generate_video. For a single image ad it is optional: generate_image alone makes one from the saved brand, so skip this step unless the user wants concepts or copy options first. A named length ("a 30 second ad") goes in durationSeconds and the storyboard is written to it; a video with none is not planned: a free question comes back to ask the user (15s is one clip, or 30s, or any 4-180). The user’s own screenshots or pictures to show inside the video go in inserts. The brand’s SAVED product photo (get_brand / list_product_photos) is used automatically; never ask the user to upload it again. Uses credits for the planning step.
Inputs: product (required), hook, brand, draft, +13 more.
plan_variationsPlan ad variationsAInspect
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. To plan AND render a batch of finished static ads for one or several products in one call (up to 20 per product), use make_static_ads.
Inputs: product (required), brand, count, get_cost, +3 more.
plan_weekPlan a week of postsAInspect
Use this when the user wants a week of social posts planned, or answers yes or no to planning their week. It drafts one batch of 5 posts for the active brand: a new image, a caption and a suggested day and time for each. Without confirm it returns the price and whether the batch fits the account’s posting allowance, and spends nothing. confirm:true starts the batch and bills credits; read the posts with get_job. The posts stay drafts until the user approves them with run_post_refill, and this tool publishes nothing. decline:true records that the user said no.
Inputs: confirm, decline, get_cost, timezone, +2 more.
post_editPost-production editAInspect
MECHANICAL post-production on an EXISTING video (URL): ordered ffmpeg primitives, ~2 credits flat, NO AI model, outputs a NEW video. Ops: a branded end card, trim, speed (0.5-2x), mute (whole or a window), audio_gain (-20..+6 dB), fade_out, music (a ducked bed: omit track = a free library track picked by mood, no attribution; or track = an audio link (upload_file, find_sound or generate_sfx URL, or a post's sound); track 'generate' composes it, paid, ONLY when the user asks; start/end, db, replace), voiceover (text spoken OVER it, its sound ducked; ~2.5 words/s; voice female|male; +~1 credit), watermark (brand logo), grain (anti-AI), text (timed words in a native look: style 'tiktok-classic' default / 'clean-minimal' / 'note-style' or a textStyle; start/end, or at:{word} and until:{word} to time them to speech), join (this video FOLLOWED BY clips[]: Library URLs, files or public post links, one 1080x1920 video), layout (ONLY when asked: split screen, cut-out or green-screen presenter, letterbox, fisheye; whole or a start/end window). Presets are shortcuts: x/y, grain amount, join transition and bridge sound are free. 'A viral hook, then our clip' = videoUrl: the hook's post link + [{op:'join', clips:[{url: ours}], bridge}], and it ALWAYS gets a bridge unless the user asks for a bare cut: {kind:'impact'} cuts the hook just before its payoff (cutAt overrides) and lands our clip on a punch-in and flash, with the payoff sound FROM THE HOOK ITSELF (else one generated from its frames, up to 8 credits, else a neutral impact). {kind:'text', text, then?} only when words over the cut are asked for. No voiceover bridge. ANY OTHER EDIT, op or bridge (whip, zoom, freeze, wipe, generated shot) is edit_timeline: free keyframes, any size. NEVER generate_video/render_ad for these. Feedback is one named move, never a re-render: quieter/louder (music db, audio_gain), faster/slower (speed; slower = zooms and pans at 0.7x), tighten (trim), retime (word anchor), recut (order, in/out), regrade (timeline colour keys).
Inputs: ops (required), videoUrl (required), accent, domain, +5 more.
post_performanceWhich hooks and subjects are getting tractionARead-onlyIdempotentInspect
Use this when the user asks which of their posts, hooks or subjects work best. It groups this brand's published posts 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 WILL NOT DO, to repeat rather than paper over: (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.
Inputs: axis, days, brand, channel.
post_to_blueskyPost to BlueskyADestructiveInspect
Use this when the user wants to post to Bluesky. Publishing costs no credits. 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 and says which limit. 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. Returns the post's public bsky.app URL. Connect at Connectors > Bluesky. Full rules: get_instructions({topic:'post_to_bluesky'}).
Inputs: text (required), hook, brand, langs, +14 more.
post_to_discordPost a Discord announcementADestructiveInspect
Post to the user's Discord server. Free. With the Hermoso bot added it posts as the bot to channel (or the brand's default channel) with attachments up to 25 MB a message, replyTo, threadId (inside a thread), startThread (a thread under the post) and threadName (a forum channel); the messageId it returns ("/") is what edit, delete and get_discord_message take. Without the bot it posts through the brand's announcement webhook (never the alert one): ≤2000 characters, files up to 20 MB attached (up to 10), larger ones as links. Mentions never ping unless mentions:true. EITHER WAY it can carry embeds (up to 10 rich cards, 6000 characters between them), a native poll (question, up to 10 answers, 1 to 768 hours; get_discord_poll reads the votes) and tts (read aloud). A webhook post can also take a display name and avatar for that one post (username, avatarUrl); crosspost:true (bot only) also publishes the post to every server that follows the announcement channel. Anything over a Discord limit is refused, never cut. Reactions are the only per-post number (get_discord_message). Not connected: connect_connector with provider discord and no fields returns the install link.
Inputs: tts, hook, poll, text, +21 more.
post_to_google_businessPost to Google Business ProfileADestructiveInspect
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 (Connectors > Google Business Profile).
Inputs: hook, link, brand, title, +14 more.
post_to_linkedinPublish to LinkedInADestructiveInspect
Use this when the user wants to post to their personal LinkedIn profile. Publishing costs no credits. Publish a post to the user’s connected LinkedIn profile — text, and optionally an image (imageUrl), a VIDEO (videoUrl, with captionsSrt and a videoThumbnailUrl cover), a 2–20 image MULTI-IMAGE post (imageUrls), a LINK post with a real preview card (linkUrl + linkTitle / linkDescription / linkThumbnailUrl — LinkedIn never scrapes the page), a DOCUMENT post (documentUrl: a PDF / PPTX readers swipe through), and @mentions of companies (mentions). 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 (Connectors > LinkedIn).
Inputs: text (required), hook, poll, brand, +21 more.
post_to_linkedin_pagePublish to a LinkedIn company PageADestructiveInspect
Use this when the user wants to post to a LinkedIn company Page. Publishing costs no credits. 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. 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). Full rules: get_instructions({topic:'post_to_linkedin_page'}).
Inputs: text (required), hook, poll, brand, +26 more.
post_to_metaPost to Facebook, Instagram or ThreadsADestructiveInspect
Use this when the user wants to post now to Facebook, Instagram or Threads. 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, an ad made here or the user’s own 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. This PUBLISHES immediately — confirm the copy + media with the user first. Needs a connected Meta account (Connectors > Meta) with posting permission; Threads needs its own connection.
Inputs: hook, link, async, brand, +56 more.
post_to_pinterestCreate a PinADestructiveInspect
Use this when the user wants to publish a Pin to Pinterest. Publishing costs no credits. 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 (Connectors > Pinterest).
Inputs: boardId (required), hook, link, brand, +19 more.
post_to_shopify_blogPublish a Shopify blog articleADestructiveInspect
Use this when the user wants to publish, draft or schedule a BLOG ARTICLE on their Shopify store's blog. Publishing costs no credits. Works for the Shopify store connected to this brand (Connectors > Shopify, or connect_shopify_store) or the store this account was installed on. A title is REQUIRED and the text becomes the body: plain text or light markdown (## headings, - lists, bold, links) becomes HTML, and HTML is sent as written. status: publish (default), draft, or scheduled with a future date, which Shopify schedules natively. The FIRST image becomes the featured image (Shopify copies it into the store); other images and a video go inside the body by their own links. A store with one blog needs no blog named; with several, pass blog (list_shopify_blogs); newBlogTitle creates a blog with the article. The reply is Shopify's own copy of the article, with its public address once published. An over-long tag is refused, never cut. A store that installed Hermoso before blog posts existed is asked to open the app once and approve the new permission. Shopify has no view counts on a blog article: never quote one.
Inputs: title (required), blog, date, hook, +19 more.
post_to_slackPost a Slack announcementADestructiveInspect
Post to the user's Slack. Free. With the Hermoso app installed it posts as the app to channel (or the brand's default channel), uploads images and video, replies in a thread (threadTs) or schedules in Slack (postAt, text only, ≤120 days); the messageId it returns ("/") is what edit_slack_message, delete_slack_message and get_slack_message take. Without the app it posts through the brand's announcement webhook (never the alert one): text ≤40,000 characters (refused, never cut), a title line, png/jpg/gif images by link, video as a link; a webhook post has no id, so it cannot be edited, deleted or measured. Not connected: connect_connector with provider slack and no fields returns the install link.
Inputs: hook, text, brand, title, +18 more.
post_to_telegramPost to TelegramADestructiveInspect
Use this when the user wants to post to a Telegram channel or group. Publishing costs no credits. 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. @yourchannel) or its numeric id (a group is negative; a supergroup or channel starts with -100). 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. 0 credits. Connect at Connectors > Telegram. Full rules: get_instructions({topic:'post_to_telegram'}).
Inputs: chatId (required), hook, text, brand, +17 more.
post_to_tiktokPost a video or photo post to TikTokADestructiveInspect
Use this when the user wants to post a video or photo post to TikTok now. Publishing costs no credits. 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. destination:"post" (THE DEFAULT) publishes it LIVE on their profile: TikTok requires the user to CHOOSE the privacy themselves (no default is allowed), so call tiktok_creator_info, show them their real privacy options, and get their choice and an explicit yes before calling. destination:"draft" is ONLY for when the user asks for a draft, or wants to add a TikTok sound or trending audio (TikTok’s API takes no sound for a VIDEO): BEFORE sending, tell them plainly it lands in their TikTok inbox as a DRAFT, that they add the sound in TikTok’s editor, and that THEY must publish it from the TikTok app — nothing goes live until they do. Never pick draft on your own. A photo post published with destination:"post" gets a TikTok-recommended track automatically (autoAddMusic, default on) that they can change in the app. Pass Hermoso render URLs (or upload_file urls for local/external files). Needs TikTok connected (Connectors > TikTok).
Inputs: hook, brand, title, ideaId, +26 more.
post_to_webflowPublish a Webflow blog postADestructiveInspect
Use this when the user wants to publish or draft a BLOG POST on their Webflow site. It becomes an item in the site's blog CMS collection. Publishing costs no credits. A title is REQUIRED and the text becomes the body: plain text or light markdown becomes HTML in the collection's rich text field, and HTML is sent as written (Webflow's API cannot take code blocks, so a body with one is refused). Hermoso maps the post onto the collection's OWN fields: title and slug, the body, a summary field, a cover image field (up to 4 MB), and search title and description fields when the collection has them. A part the collection has no field for is refused by name, never dropped. REQUIRED FIELDS of the collection are filled from the post where they can be: a required Title or Headline field takes the title, an Intro or Summary field the excerpt (else the first lines of the body), every required image field the cover image. A required Author, Category or other choice is NEVER guessed: the refusal names each such field's slug, type and allowed values (a Reference's items by name and id, an Option's options), and you pass them in fieldData by slug; a Reference or Option value may be the item's or option's id or its name. fieldData also sets any other field. status: publish (default) or draft. Webflow's API CANNOT SCHEDULE a post: for a later time use schedule_post with the webflow channel. The reply is Webflow's own copy of the item, with its public address. Webflow has no view counts on an item: never quote one. Not connected: the user connects it under Connectors > Webflow, or you call connect_connector with provider webflow (token).
Inputs: title (required), hook, slug, text, +16 more.
post_to_wixPublish a Wix blog postADestructiveInspect
Use this when the user wants to publish, draft or schedule a BLOG POST on their Wix site. Publishing costs no credits. A title is REQUIRED (up to 200 characters) and the text becomes the body: plain text or light markdown is turned into Wix's own rich content, and HTML is converted by Wix (up to 30,000 characters). status: publish (default), draft, or scheduled with a future date, which Wix schedules natively. The FIRST image becomes the cover; other images and a video are brought into the site's Media Manager and placed in the body. tags and categories take names; one the blog lacks is CREATED, and the reply says which categories. A title over 200 characters, an excerpt over 500, a slug over 100 or more than 30 tags is refused, never cut. The reply is Wix's own copy of the post, with its public address once it is live. Not connected: the user connects it under Connectors > Wix, or you call connect_connector with provider wix (apiKey, siteId).
Inputs: title (required), date, hook, slug, +18 more.
post_to_wordpressPublish a WordPress blog postADestructiveInspect
Use this when the user wants to publish, draft or schedule a BLOG POST on their WordPress site. Publishing costs no credits. A title is REQUIRED and the text becomes the body: plain text or light markdown (## headings, - lists, bold, links) is turned into WordPress blocks, and HTML is sent as written. status: publish (default), draft, pending (submit for review), private (logged-in editors only) or future with a date — a future date makes WordPress schedule it natively. The FIRST image becomes the FEATURED image, every other image is uploaded and placed inline, and a video is uploaded and embedded (if the site's host refuses the file as too large, the post plays it from its own link and the reply says so). categories and tags take names or ids; a name the site lacks is CREATED and the reply says which. An over-long title is refused, never cut. WordPress has NO per-post views in its API: never quote a view count for a WordPress post. Works on a self-hosted site and on a site hosted on WordPress.com, whichever the brand connected. Not connected: the user connects it under Connectors > WordPress, or you call connect_connector with provider wordpress (siteUrl, username, appPassword).
Inputs: title (required), date, hook, slug, +15 more.
post_to_xPublish a post to X (Twitter)ADestructiveInspect
Use this when the user wants to post to X (Twitter) now. 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. Text is NEVER truncated. Write altText whenever you attach a render. COSTS CREDITS at X’s per-post price, every post in a thread billed: a post that contains a link (any web address, and every quote post) is X’s link rate, far higher than one without (hermoso_credits gives both figures). When the user asks what a post will cost, call this with dryRun:true: it posts NOTHING and returns that exact post’s costCredits. THIS TOOL POSTS ORGANICALLY — it does not create an ad campaign. Needs X connected (Connectors > X). Full rules: get_instructions({topic:'post_to_x'}).
Inputs: clip, hook, poll, text, +26 more.
post_to_youtubePost a video to YouTubeADestructiveInspect
Use this when the user wants to upload a video or Short to YouTube. Publishing costs no credits. 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). PUBLISHES PUBLICLY BY DEFAULT: a plain "post this to YouTube" puts it ON the channel (confirm the title with the user, as for any publish) and notifies subscribers as YouTube does. Pass the privacy the user states instead: "unlisted" (link-only) or "private" (eyes-only). A video meant to run as a YouTube/Google AD should go up "unlisted" — private videos CANNOT be used as ads. Never choose unlisted for music on your own. Needs a connected YouTube channel (Connectors > YouTube). Full rules: get_instructions({topic:'post_to_youtube'}).
Inputs: videoUrl (required), hook, tags, brand, +26 more.
post_x_articlePublish a long-form Article to XADestructiveInspect
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. 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. Costs credits (X bills per API request, and this is three of them). Needs X connected (Connectors > X). Full rules: get_instructions({topic:'post_x_article'}).
Inputs: body (required), title (required), hook, brand, +8 more.
product_sizzleProduct sizzleAInspect
Render an 18-30s PRODUCT SIZZLE: ONE 15s Seedance 2.5 hero clip of the product, diced into fast cuts and intercut with typeset spec/CTA cards on a brand-coloured grain background. No music unless asked (music / musicMood); its own sound carries the cut. 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 2.5 render: ≈870 credits at the DEFAULT 1080p, ≈360 at 720p, ≈170 at 480p; a 4k ask renders on Seedance 2.0, the only Seedance tier with 4k, ≈2,360 (call hermoso_capabilities for the live seedance-2.5 per-duration numbers; the dicing and the cards are free; an asked-for bed adds a few). 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.
Inputs: prompt (required), cta, music, specs, +10 more.
publish_to_shopify_productPublish an image or video onto a Shopify productADestructiveInspect
Attach a finished IMAGE or VIDEO 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 mediaUrl, which is what every Hermoso render returns. Whether it is a video is read from the file (.mp4 / .mov / .webm, or the link's content type); pass kind to say so outright. An image is fetched by Shopify directly; a video is uploaded to Shopify for you (MP4, MOV or WEBM, up to Shopify's 1 GB and 10-minute product-video limits; a file over a limit is refused by name, never cut). Shopify processes media asynchronously: the reply is the status read back from Shopify, and READY means it is live on the listing while PROCESSING means it will appear when Shopify finishes. That is success, not a failure. Works for the Shopify store connected to this brand (Connectors > Shopify, or connect_shopify_store) or the store this account was installed on. Free: the render was already paid for.
Inputs: productId (required), alt, kind, imageUrl, +1 more.
pull_competitor_adsPull competitor adsAInspect
Use this when the user names a brand and asks what ads it is running ("show me the ads is running"). It pulls that brand’s live ads from the Meta (Facebook and Instagram) Ad Library, deduplicated and sorted, in a few seconds. Covers the Meta Ad Library only; for a broader search across brands or platforms use research_ads. Spends credits.
Inputs: url, name, sort, brand, +9 more.
query_notion_databaseRead a Notion databaseARead-onlyIdempotentInspect
Read the ROWS of a Notion database the user shared with Hermoso — e.g. the team's content calendar: each row's title, id, link and every property as a plain value (status, date, channels, caption, links), plus the database's columns with their types and options. Filter with match {"Status": "Scheduled"} (typed from the database's own columns) or a raw Notion filter object; sort with sortBy (a column, or created_time / last_edited_time) and direction. Up to 100 rows per call, cursor for more; the answer says when Notion stopped at its 10,000-result limit. Use it to import a calendar and schedule its posts, or to find the row update_notion_row changes. Read-only, free. Needs Notion connected (Connectors > Notion).
Inputs: limit, match, cursor, filter, +5 more.
read_docRead a Google DocARead-onlyIdempotentInspect
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 of EVERY tab (each headed by its tab name when there are several), with smart chips (dropdowns, people, dates, rich links) shown as the text Docs displays, plus dropdowns[] — each chip with its title, current value and options, which is what update_doc dropdowns sets. Read-only, free.
Inputs: docUrl, documentId.
read_notion_pageRead a Notion pageARead-onlyIdempotentInspect
Read a Notion page the user shared with Hermoso, as markdown (pageId or a Notion link). A database id answers with its data sources instead. Read-only, free.
Inputs: pageId (required).
read_sheetRead a Google Sheet rangeARead-onlyIdempotentInspect
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.
Inputs: range, sheetUrl, spreadsheetId.
recast_motionRecast motionAInspect
Copy the motion of any video (motion transfer): re-perform a clip's motion, camera and timing with YOUR character, product, clothes or place; sound kept. image (+ images, @Image1, @Image2… in prompt) = who and what. engine auto (default): a person clip + ONE photo of a person (saved, real or AI), 4-30s -> seedance (Seedance 2.5 through our face library, 720p: the clip's scene, beats and sound kept, the WHOLE person swapped) when the clip is one of our renders or faceRoute is set; otherwise wan (Wan 3.0, scene kept, 3-15s, 720p), past 15s kling-edit (Kling 4.0 Edit, 3-30s, 1080p by asking); several photos (one per person) -> h3 (H3 Max Recast, ≤4 photos, 5-30s); no person in the clip -> seedance. By name: kling-edit; wan = Wan 3.0 (≤15s, keeps the set); wan-prime; h3; kling = Kling Motion Control (ONE picture, its background becomes the set). voice/language: the new performer gets a new voice (same timing) or speaks another language (lip-synced), in the same job and price. Billed per output second, ~5 min per 5s; dryRun quotes.
Inputs: video (required), tier, image, voice, +11 more.
reframe_videoReframe videoAInspect
Reframe a video to a different aspect ratio (e.g. 16:9 master -> 9:16 vertical): the whole original frame is kept and the new canvas around it is generated, with the sound and timing unchanged. Clips up to 300 seconds. Paid render; returns the served URL of the reframed video. Every placement at once (a free blur-pad by default): repurpose_video. A presenter on any video: add_presenter.
Inputs: video (required), aspectRatio (required), get_cost, idempotency_key, +1 more.
rememberRemember a factAInspect
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.
Inputs: text (required), brand, category.
remix_staticClone a static ad (old name)AInspect
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.
Inputs: imageUrl (required), brandId, get_cost, idempotency_key, +1 more.
remove_memberRemove a teammateADestructiveIdempotentInspect
Remove a member from this profile by email — they lose access (you can re-invite them later), AND every connection THEY made on this profile is disconnected with them: their own X, LinkedIn, TikTok, YouTube, Pinterest, Threads… connections (on a channel holding several accounts, only the accounts they added), and any extra login or authorization they added. Connections the owner or anyone else made are never touched, and one with no record of who connected it is treated as the owner's. Queued posts that would publish through their accounts, or that they scheduled themselves, will not go out. The unconfirmed call reports exactly which connections and how many scheduled posts — relay that to the user, then call with confirm:true.
Inputs: email (required), confirm.
render_adRender ad videoAInspect
Use this when the user asks for a video ad, Reel, TikTok ad, UGC video or commercial for their business or product It renders a finished ad on a real video model, on their brand (real product photos, brand voice), as an mp4 ready to post: timed shots, clean speech, text set in post, no music, captions or end card unless asked. Pass plan_ad’s full output as creative (plan_ad turns a one-line ask into the concept). Most models cap a clip at 15s and the longest at 30s: dryRun:true shows the act split free, before spending. The brand’s saved product photo (get_brand / list_product_photos) is the real product in the shots, with no upload needed. CAST A SAVED CREATOR with creator (list_creators) so the same person stars in every ad; otherwise each render casts a new face. The user’s own pictures (creative.inserts, or inserts) are laid in full screen at their seconds. An app shown on a device screen with no real screens to lay there returns needsAppScreens, nothing charged: ask, then pass screenChoice or screens. 1–3 min; poll get_job while it renders. Spends credits. Full rules: get_instructions({topic:'render_ad'}).
Inputs: creative (required), board, model, music, +23 more.
report_bugReport a bugAInspect
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.
Inputs: details (required), summary (required), severity.
repurpose_videoRepurpose a video for every placementAInspect
ONE video in, EVERY placement out, in one job, as a named file list ([_].mp4) with a manifest. Placements: 'everywhere' (default: 9:16, 4:5, 1:1, 16:9), any W:H, a pixel size (1200x628) or a platform word (tiktok, reels, stories, feed, square, youtube, linkedin, pinterest). Each is reframed by a BLUR-PAD by default (the whole frame over a blurred copy of itself; free, no AI), reframe 'crop' (fill, edges cut; free) or 'ai' (the new canvas generated around the frame; paid, for a canvas the engine makes, else padded and said). A placement may be {placement, reframe} to mix. Optional captions (word-timed, ~4 words a cue, placed for each canvas) and languages (a lip-synced dub per language; every placement of each). A pack of pads and crops only is billed 0. dryRun:true = the exact price (the sum of every leg's own price), which is what it charges. For ONE canvas use post_edit op pad.
Inputs: video (required), pad, name, dryRun, +8 more.
request_featureRequest a featureAInspect
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.
Inputs: details (required), summary (required).
reschedule_postChange a scheduled postADestructiveIdempotentInspect
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.
Inputs: id (required), at, link, poll, +121 more.
research_adsResearch adsAInspect
Use this when the user asks an open-ended ad question across several brands or platforms, such as comparisons, which angles are working in a market, or ad examples for a category. Do not use for one named brand’s current ads: pull_competitor_ads covers that. 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.
Inputs: query (required), brand, get_cost, idempotency_key, +1 more.
resize_adResize a static ad for other placementsAInspect
Re-lay out ONE finished static ad for other placements: the same ad, product, copy (word for word), logo and style, recomposed natively for each canvas rather than cropped. Pass image and optionally aspectRatios from 1:1, 4:5, 9:16, 16:9, 3:4, 4:3 (default 1:1, 4:5 and 9:16; the ad's own ratio is skipped). Reads the ad's text first (3 credits) so every line survives, then one image edit per canvas. When the saved brand has a product photo and the ad shows that product, the photo rides with the edit and the product's label is read and checked against it: re-printed from the photo only when it came out wrong (the check alone is charged when it is right; one small extra charge finds the product first). fixLabel:false turns that off. Priced before it runs. Several sizes AND versions (headlines, languages, offers) at once: repurpose_image. For VIDEO use reframe_video.
Inputs: image (required), fixLabel, get_cost, aspectRatios, +2 more.
restyle_videoRestyle a videoAInspect
RESTYLE a clip into a new LOOK: every frame redrawn, shots, motion, camera, framing, timing and sound kept. Looks: Restyle looks in hermoso_capabilities (claymation, knitted yarn, cel-shaded CG anime…), your own words, or a look BUILT FROM YOUR IMAGES (styleImages); characters draws your own characters in. engine auto (default) picks by what is in the clip: a real-looking person -> kling (Kling 4.0 Edit, 3-15s); none -> wan (Wan 3.0, recommended, ≤15s) else seedance (Seedance 2.5, 4-30s); wan-prime = Wan 3.0 Prime by name (costs more). Paid; dryRun quotes it. One change only: edit_video.
Inputs: video (required), style, engine, describe, +7 more.
resume_jobResume a stopped filmAInspect
Finish a video-blocks explainer or faceless-channel film (make_explainer) that STOPPED partway: a block the video model would not render, or a server restart. What it already made is kept (the script, the style key, the narration and every block that rendered), so this renders ONLY the missing blocks and re-assembles the same film, with the same topic, look, voice, length and options. It reserves credits only for what is missing and never charges again for what was kept. get_job and list_jobs show which jobs can be resumed and which blocks are kept. Quote it with dryRun first and tell the user the number. A finished film is not resumed: to redo one block of a finished film, use fix_beat with its job id.
Inputs: jobId (required), dryRun, get_cost, idempotency_key, +1 more.
retry_scheduledRetry a failed scheduled postADestructiveInspect
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), and by default this re-fires ONLY the channels that did not succeed (list_scheduled reports them as retryable). It re-queues the same content as a NEW post that goes out RIGHT AWAY, within seconds; the original keeps its failure record. Naming a channel that already published is REFUSED rather than posted twice: a channel that published can only REPLAY (nothing is posted), and one whose outcome is UNRESOLVED (the platform timed out and may be holding the post) refuses with that reason instead of guessing. Fix the cause 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. 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.
Inputs: id (required), at, brand, chatId, +9 more.
run_post_refillRun autopilot now / approve its draftsADestructiveInspect
Run AUTOPILOT POSTING (autoposting, paid plans only) NOW instead of waiting for its daily turn, or review the drafts it made: schedule them, delete one, change a caption, or save a note such as "too salesy". By default it is a preview: it returns the posts it WOULD make — each new picture’s scene, the caption, the channels and the price — rendering nothing and queueing nothing. The preview still WRITES the scenes and copy with a model, which bills its model cost (the reply says exactly how many credits). dryRun:false actually renders a fresh image or video for each post within the budget (credits are spent) and then, by mode, schedules them ("auto") or keeps them as drafts ("review"). It never re-posts the Library. REVIEWING A BATCH: pass approve (draft ids, or ["all"]) to schedule drafts, discard to delete them, edit ([{id, message?, captions?, title?, at?, channels?}]) to change one first (a new at reschedules it); get_post_refill lists them. learn saves notes future batches follow (free). redo remakes ONE draft from a note and is paid; without confirm:true it returns only the price. A scheduled post can still be pulled before it goes out with cancel_scheduled. Every caption is screened against the voice rules and a failing one is dropped, so a plan can come back shorter than the cadence — the reason is in the notes.
Inputs: edit, redo, force, learn, +3 more.
save_creatorSave a creatorAInspect
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 an AI person, or a photo of a real person you have permission to use, or of yourself; never a photo just because it is public) 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 (the one paid option is makeSheet, which makes their 16:9 character sheet). LIKENESS: leave source "generated" for an AI-made person (free on every plan) and use "upload"/"social" for a REAL person. Using a real person’s face, likeness or voice confirms you are them or have their consent, take full, unlimited responsibility for its use and will cover any claim against Hermoso (hermoso.ai/terms). Paid plan only; recorded.
Inputs: name (required), look, brand, image, +6 more.
save_playbookSave a playbookAInspect
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.
Inputs: name (required), brand, hooks, plays, +3 more.
save_skillSave a skillAInspect
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).
Inputs: name (required), directive (required), brand.
save_to_driveSave file(s) to Google DriveAInspect
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 (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.
Inputs: url, name, urls, folder.
save_to_notionSave to NotionAInspect
Save to the user's Notion as a NEW page: a research report, competitor teardown or campaign report as content (markdown: headings, lists, links, and an image or video URL on its own line becomes the media), a swipefile collection (swipefileCollection: name or id; each ad with its creative, copy, run dates and link), the content calendar (includeSchedule:true), or a mix. Put it under parentPageId, as a row in databaseId, or omit both for a private page in their workspace. Long text is split across blocks, never cut. The answer is read back from Notion. Free; never overwrites anything.
Inputs: icon, title, content, databaseId, +4 more.
save_to_onedriveSave file(s) to OneDriveAInspect
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 (Connectors > OneDrive).
Inputs: url, name, urls, folder.
save_to_swipefileSave ads to the swipefileAIdempotentInspect
Save one or more ads/creatives to a named SWIPEFILE collection, creating the collection if it does not exist — the headless twin of the heart 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.
Inputs: items (required), collection (required), brand.
schedule_postSchedule a post for laterADestructiveInspect
Use this to schedule a social media post for later, on one channel or several. Costs no credits (X alone bills per call: hermoso_credits). FREE PLAN: 5 posts a month on up to 3 channels (a post counts once; UTC month); paid plans are unlimited. Over it the post is refused and nothing is queued: relay the refusal as written, never retry or split the post. A MULTI-SLIDE creative goes in imageUrls[] as a CAROUSEL, in order, never just slide 1. Name the time in at, or pass useQueue:true for the brand’s next free POSTING SLOT (“just queue it”). Hermoso never guesses the account: Pinterest needs boardId (list_pinterest_boards), else refused; a LinkedIn COMPANY PAGE post needs linkedinOrganizationId (list_linkedin_pages), else it goes to the person’s own profile. Several Facebook Pages need pageId (list_meta_pages), for Facebook and for an Instagram that posts through a Page: none named is refused at scheduling with the Pages listed, so ask the user which. Resolve these FIRST; let the user pick. Posts GO LIVE PUBLICLY by default. Full rules: get_instructions({topic:'schedule_post'}).
Inputs: channels (required), at, hook, link, +125 more.
score_adScore adAInspect
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, own: could another brand run it unchanged), strengths, and the single biggest fix. Use BEFORE spending on distribution, or to rank variants.
Inputs: url (required), kind, intent, get_cost, +2 more.
search_google_adsSearch Google adsAInspect
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.
Inputs: limit, domain, region, get_cost, +3 more.
search_instagramSearch InstagramAInspect
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, handle, plays, likes, comments, seconds, postedAt, link, cover} per reel, ranked by plays. It matches captions worldwide and cannot be limited to a country or language: for one market, search in the words people there use, or read named local accounts' Reels through fetch_social_data's Instagram profile endpoint, which is the better first step for a local market. Spends about a credit.
Inputs: query (required), page, limit, get_cost, +3 more.
search_linkedin_adsSearch LinkedIn adsAInspect
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's library includes impression counts. Spends about a credit.
Inputs: limit, company, keyword, get_cost, +4 more.
search_meta_adsSearch Meta adsAInspect
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 across platforms, use research_ads instead. Spends credits on each ad-library read it makes: one for a keyword; for a brand name, the page lookup and its ads. An advertiser search returns only that advertiser's ads, or none plus similarly named pages to retry by pageId.
Inputs: limit, query, domain, pageId, +7 more.
search_meta_placesFind a place to tag on Instagram or FacebookAInspect
Find a PLACE to tag on an Instagram or Facebook post: a shop, cafe, restaurant, venue or landmark. Give its name with the city ("Blue Bottle Coffee Oakland"), or paste its Facebook Page link, an Instagram place link (instagram.com/explore/locations/...) or its numeric id. A pasted link or id is read and comes back as that Page's taggable pageId with its name and address, or a plain reason it cannot be tagged. Returns a handful of matching Facebook Pages that have an address: pageId, name, address, category, link. Pass the chosen pageId as locationId (Instagram) or place (Facebook) on post_to_meta, or instagramLocationId on schedule_post. These are matches to CONFIRM with the user (check the name and address; a place tag is public), and Instagram checks the place when the post is made. Needs no connected account. Spends about 1 credit per Page it checks (a name search checks up to 5 Pages, so about 5 to 7 credits); a pasted Facebook Page link or numeric id is about 1 credit; an Instagram place link costs nothing.
Inputs: query (required), near, limit, get_cost, +2 more.
search_postsTop posts about any topic, brand or productAInspect
The POSTS people make ABOUT a subject — a brand ("liquid death"), a product, a hobby ("coffee"), a hashtag ("#homecafe") — from whoever posted them, across organic TikTok, Instagram Reels and YouTube in ONE call, ranked by views. Not the brand's own ads (search_meta_ads / research_ads) and not the people (find_creators folds these same posts into creators): use it to see what is actually being posted and watched about a subject, to find clips worth cloning (clone_video), and to read the hooks and angles an audience already responds to. About one credit per platform searched (one query each by default; queries adds "best X" / "X review" / #tag variants, each a paid call); repeats inside 20 minutes are free.
Inputs: topic (required), limit, queries, get_cost, +3 more.
search_redditSearch RedditAInspect
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.
Inputs: query (required), limit, get_cost, idempotency_key, +1 more.
search_threadsSearch ThreadsAInspect
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.
Inputs: query (required), limit, get_cost, idempotency_key, +1 more.
search_tiktokSearch TikTokAInspect
Organic TikTok keyword search (there is NO TikTok ad library) — top-performing videos to mine for hooks/trends/remixable creative. Returns compact JSON {desc, handle, followers, plays, likes, comments, shares, seconds, postedAt, link, cover} per video, ranked by plays. region sets where TikTok is read from, not where posts come from. Use research_ads for open-ended research; for what to POST, tiktok_ideas; for formats across a category, find_proven_formats. Spends about a credit.
Inputs: query (required), limit, region, sortBy, +8 more.
search_youtubeSearch YouTubeAInspect
Organic YouTube keyword search (/v1/youtube/search) — videos to mine for hooks/angles/long-form structure. Returns compact JSON {desc (title), author, handle, plays, seconds, postedAt, link, cover} per video, ranked by views. Spends about a credit.
Inputs: query (required), limit, region, sortBy, +5 more.
send_smsSend an SMS, MMS or RCS messageAInspect
Send a text from one of the brand's own Twilio or Telnyx numbers: to (one number or a list of up to 100, E.164), text (up to 1,600 characters), media (up to 10 pictures for an MMS: a Library id, attachment://N or an https link), from (needed when the account has several numbers), sendAt (ISO time, to schedule it; on Twilio this needs a Messaging Service set with set_sms_settings). channel "rcs" sends RCS through the brand's Twilio RCS sender (rich cards via contentSid HX… + contentVariables), falling back to SMS unless fallback:false; channel "whatsapp_sandbox" sends through Twilio's WhatsApp Sandbox to testers who joined it (rcs_setup, whatsapp_sandbox). The answer has each message's id, segment count and status; delivery status follows (get_sms_status). Any optional sending settings the connection turned on (quiet hours, opt-out list) apply. On the brand's own account no credits (the provider bills it); on Hermoso phone 0.8 credit a segment, 2.5 an MMS. Needs Hermoso phone on (activate_phone_service) or Twilio or Telnyx connected (Connectors, or connect_connector).
Inputs: to (required), from, text, media, +8 more.
set_auto_reloadSet auto-reloadAIdempotentInspect
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.
Inputs: enabled (required), reloadCredits, thresholdCredits.
set_competitor_watchSet the market radarADestructiveIdempotentInspect
Set, change or stop a brand's MARKET RADAR (the standing competitor watch; Ad Spy > Watching in the web app; each brand has its own), run weekly or daily: newAds (what watched brands launched), winners (their ad passing 30 days running), trends + topPosts (formats and most-viewed posts for niche topics), ideas (3 to make). Only what you pass changes. competitors / topics REPLACE their lists (max 8 brands, 5 topics); both empty stops it and clears findings. auto:true picks 3-5 competitors, 2-3 similar brands and 2-3 topics from the saved brand or seed (one model call, billed at its token cost). dryRun:true quotes one check, saves nothing. Saving is free; each check holds its quote first and is skipped when the balance is short. runNow is refused while a check runs or just after one finished. Read it with list_watch_findings.
Inputs: auto, seed, brand, email, +7 more.
set_connector_accountsChoose which accounts a brand may useADestructiveIdempotentInspect
Set WHICH of a connector's accounts this profile 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, pinterest, instagram, meta, google_ads, linkedin, pinterest_ads, linkedin_ads, reddit_ads, apple_ads, amazon_ads, microsoft_ads, google_business, google_analytics, snapchat_ads, x_ads, tiktok_ads, google_tag_manager, google_search_console, bing_webmaster. Free.
Inputs: provider (required), accountIds (required).
set_post_refillSet up, change or pause autopilot postingADestructiveIdempotentInspect
Turn AUTOPILOT POSTING (autoposting, the posting refill) on, change it or pause it. Available on paid plans: on the Free plan switching it on is refused, so relay that and do not retry. PASS ONLY WHAT CHANGES. It always makes NEW posts (a fresh image, carousel or video for each) and never re-posts the Library. Ask the user for anything missing (goal, mode, channels) rather than guessing. mode picks what happens to each batch: "review" (the default) keeps the fresh posts as drafts until a human approves them (run_post_refill approve), "auto" schedules them straight away. enabled:false is the PAUSE — it removes the recurring job outright, and posts already queued are left alone (cancel those with cancel_scheduled). Full rules: get_instructions({topic:'set_post_refill'}).
Inputs: goal, mode, avoid, queue, +21 more.
set_product_imageSet product photoADestructiveIdempotentInspect
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 profile — switches this key's active profile like use_brand).
Inputs: imageUrl (required), brandId, source_note.
set_roleChange a teammate’s roleADestructiveIdempotentInspect
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.
Inputs: role (required), email (required), confirm.
stitch_videoStitch multi-scene videoAInspect
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.
Inputs: scenes (required), model, voice, get_cost, +6 more.
store_getRead a workspace storeARead-onlyIdempotentInspect
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.)
Inputs: key (required), limit.
subscribe_linkedin_leadsTurn on real-time LinkedIn lead deliveryAIdempotentInspect
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.
Inputs: pageId, leadType, forwardTo, adAccountId.
tidy_memoryTidy the Memory listADestructiveIdempotentInspect
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 model call, billed at its token cost.
Inputs: brand, confirm.
tiktok_post_statusCheck whether a TikTok post finished publishingARead-onlyIdempotentInspect
Follow a TikTok post that post_to_tiktok sent but TikTok was still processing (it came back pending:true). Pass the publishId it returned. Answers one of three states: done (PUBLISH_COMPLETE, with the public url once TikTok’s moderation has named it; urlStatus is ready, pending, private or draft), failed (with TikTok’s reason), or still processing, which is normal for a few minutes and is NOT a failure. Never post the video again while it is processing. Free, read-only. Needs TikTok connected (Connectors > TikTok).
Inputs: publishId (required), account.
update_brandUpdate profile fieldsADestructiveInspect
Patch SPECIFIC fields of the active profile (name, domain, sells, summary, category, audience, positioning, voice, style, goal, fonts, palette, logos, brand/product name pronunciations, profileType: explore = kept but unused) WITHOUT overwriting the rest — a read-modify-write on the saved brand. Use for “change our voice to playful”, “we sell to dentists now”, “our fonts are Benne and Josefin Sans”, “our colours are #3D4C41 and #EEE4DA”. The fonts and palette are what template ads are set in and what every planned ad is told to use, so set them here rather than describing them in style. To onboard a brand from scratch, use draft_brand. If no brand is saved yet and you only INFERRED one from what the user is making, ask them to confirm it is their brand before saving it (they may be working for a client or just trying things). Only pass the fields you’re changing.
Inputs: goal, logo, name, brand, +15 more.
update_docEdit a Google Doc in placeADestructiveIdempotentInspect
EDIT a Google Doc — the correction append_to_doc cannot make. 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), or dropdowns:[{title, value}] sets a dropdown chip (e.g. Status -> Approved — read_doc lists every chip with its options; pass dropdownId when two share a title; an unknown title or option is refused with the real list and nothing changes); the same entry with options:[…] (the COMPLETE new list, 2–50) and/or newTitle changes the dropdown itself for every chip built from it, and an option you drop that a chip shows needs replace:{"Old":"New"}. 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.
Inputs: docUrl, confirm, rewrite, dropdowns, +3 more.
update_drive_fileRename / move / trash a Drive fileADestructiveIdempotentInspect
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.
Inputs: fileId (required), name, trash, moveToFolderId, +1 more.
update_notion_rowUpdate a Notion database rowADestructiveIdempotentInspect
Change properties on ONE row of a Notion database (pageId from query_notion_database) — e.g. mark a calendar row Status "Posted" and put the live post link in its URL column. properties is {"Column": value} by column name: text, number, checkbox, select (an existing option or a new one), status (must be an existing option), multi-select (array; replaces the whole value), date (ISO, or {start, end}), url, email, phone; null clears. Validated against the database's own columns before anything is sent and refused by name otherwise, never coerced; columns you do not name keep their values. Read back from Notion. trash:true moves the row to Notion's trash (restorable; returns a preview first and needs confirm:true), trash:false restores it. Free.
Inputs: pageId (required), trash, confirm, properties.
update_onedrive_fileRename / move a OneDrive fileADestructiveIdempotentInspect
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.
Inputs: fileId (required), name, moveToFolderId.
update_saved_creatorUpdate a saved creator (outreach status, note)ADestructiveIdempotentInspect
Set the OUTREACH STATUS and/or a NOTE on a creator already saved in the swipefile (find_creators -> save_to_swipefile, or the heart 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.
Inputs: key (required), note, brand, status.
update_settingsChange app settingsADestructiveIdempotentInspect
Change this account's app settings. language = the language EVERY ad, script and plan is written in from now on (chat replies follow the language the user writes in) (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. emails = turn Hermoso emails on or off by group, including turning back on what an unsubscribe link turned off. zeroRetention = ZERO CONTENT RETENTION: true keeps only ids, times, statuses, counts and costs, never the text of messages, posts, prompts or transcripts once delivered; turning it ON also clears what is already stored and cannot be undone, so call it first without confirm (the refusal lists every store it clears), tell the user, then pass confirm:true. Admins only. Only pass what you are changing. Account-wide (every profile), and it takes effect on the next call.
Inputs: theme, emails, confirm, language, +2 more.
update_sheetWrite to a range in a Google SheetADestructiveIdempotentInspect
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.
Inputs: range, values, confirm, updates, +3 more.
upgrade_planUpgrade planAInspect
Change the SUBSCRIPTION plan (admin only). No argument lists the monthly plans. Basic ($19.99) is the posting plan: Autopilot, plus unlimited posting and scheduling with NO monthly credits (it includes the same 160+ free credits as the Free plan, and monthly credits start on Starter). Starter, Pro and Studio include monthly credits and no markup on models. Every paid plan posts without a limit (Free: 5 posts a month on 3 channels). New subscriber: a Checkout URL for the human. Existing subscriber upgrading: a quote + quote_token; once the human agrees, call again with confirm:true and quote_token to charge the card on file. Downgrade: a billing-page link; it starts at the term's end.
Inputs: plan, period, confirm, quote_token.
upload_fileUpload a local file -> durable public URLAInspect
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. Kept in the Library. 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), path (a local file, ONLY when Hermoso runs on the user's own machine over stdio/CLI; the hosted connector cannot see their disk), or 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= with no body.) Returns {url, kind, bytes}.
Inputs: url, name, path, dataUri, +1 more.
upscale_videoUpscale videoAInspect
Upscale a video to higher resolution (2x) for final delivery. Paid render; returns the served URL. A 480p Seedance 2.5 draft: finish_draft (same take, native 1080p). Three engines: the default ('standard') is the safe precision upscaler; engine:'flux' is the FLUX 3 video upscaler (1080p/2K/4K) with an optional mode:'creative' detail-enhancement pass; engine:'detail' rebuilds fine detail such as hair, skin and fabric, the sharpest result for a hero shot and the most expensive. Pick 'flux' or 'detail' when the user asks for added detail rather than a faithful enlargement.
Inputs: video (required), mode, engine, get_cost, +2 more.
use_brandSwitch profileAIdempotentInspect
Pin which profile this connection acts on. Pass the profile id or exact name from list_brands. Works for your own profiles AND one another account SHARED with you (pass its name or the profile id list_brands prints); 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). On a signed-in connector it also moves every other Hermoso connector the same person signed in from the same app (e.g. all the Hermoso connectors in Claude), so they act on one profile.
Inputs: brand (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 216 tools
The set is riddled with near-neighbours: publish-now vs schedule (post_to_meta / schedule_post), profile vs company-page LinkedIn, three ad-research paths (pull_competitor_ads / research_ads / search_meta_ads), five organic search tools plus search_posts and fetch_social_data, and a dozen overlapping video transforms (post_edit, edit_timeline, edit_video, restyle_video, recast_motion, reframe_video, repurpose_video, upscale_video, change_voice, dub_video, fix_beat, insert_scene). Descriptions work hard to draw the lines, but at this volume the agent must read paragraphs before every choice, and remix_static/clone_static is a literal alias.
Most names are snake_case verb_noun (post_to_meta, create_sheet, list_brands), which is readable and largely predictable. But the convention breaks in places: noun-first or reversed forms like store_get, error_detail, billing_status, product_sizzle, hook_variants, hermoso_capabilities, and near-duplicate verbs (post_to_linkedin vs post_to_linkedin_page, remix_static vs clone_static) blur the pattern.
216 tools in a single server is an extreme mismatch: the descriptions themselves admit the full schema is hundreds of thousands of tokens and degrades tool choice, which is why they built enable_tools / find_tools / call_tool as a workaround. This is the defininition of a set that has outgrown its surface.
Coverage is genuinely vast: publishing across every major channel, scheduling lifecycle (schedule/reschedule/cancel/retry/duplicate), ads research and management, file/Docs/Sheets/Drive/OneDrive/Notion CRUD, memory, skills, playbooks, creators, billing and diagnostics. Gaps are minor relative to scope rather than structural — the domain is covered end to end.
Maintenance
Related MCP Connectors
Real-time Meta, Google, LinkedIn and TikTok ad library access for AI assistants. No API keys.
AI video studio for agents — script to MP4, b-roll sourcing, Gemini QA. 43 tools.
Ad library and ad spy for AI agents: winning Facebook and Instagram ads, competitor ads and hooks.
Make social content from your agent: hooks, AI UGC videos, competitor ads, posts to 30+ networks.
Related MCP Servers
- AlicenseAqualityDmaintenanceProvides Meta and Google Ads intelligence for AI assistants, enabling users to analyze performance, track competitors, and manage ad campaigns through natural language. It features 17 tools for generating creative concepts, scraping competitor ads, and performing deep account-level analysis.17MIT
- AlicenseNot gradedqualityDmaintenanceSearches and analyzes competitor ads and content across Meta, Google, Instagram, TikTok, and YouTube with AI-powered creative analysis and cross-platform brand discovery.1MIT
- AlicenseAqualityBmaintenanceManage ad campaigns across Meta, Google, and TikTok, create campaigns, analyze performance, spy on competitors, and generate AI creatives.520MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to create, analyze, and optimize ad campaigns across Google Ads, Meta Ads, TikTok Ads, LinkedIn Ads, Amazon Ads, and ChatGPT Ads through natural language using 400+ tools.108MIT