Hermoso

Official

Overview Schema Source Related Servers Discussions Admin

Plan an ad concept

plan_ad

Turn a brand and product brief into an ad concept with copy variants, a storyboard or image prompt, and the model IDs to render with. Renders nothing.

Instructions

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

Input Schema

TableJSON Schema

Name	Required	Description
`hook`	No	force the VISUAL scroll-stop mechanic the opening beat is built on — a hook id from list_hooks (e.g. "direct_callout", "mid_problem", "macro_asmr"). Omit to let the planner pick. A hook that cannot be delivered in this brief is DROPPED with the reason rather than rendered wrongly — an on-screen-text hook on an authentic/UGC ad is the one that bites, because that register carries zero on-screen text.
`brand`	No	brand name, or a brand profile object {name,domain,category,palette,products,…}. OMIT to use the workspace’s SAVED brand + memory automatically (see get_brand); use draft_brand to onboard a new one
`draft`	No	ONLY after a video refusal that offered a light draft: the {model, durationSeconds} it named. The plan is then authored to that length and priced on that model. Never invent one — a video the account cannot cover is refused BEFORE planning with the three options (image / add credits / this draft when one fits), and the user chooses.
`format`	No	'image', 'video', or 'auto' when unspecified
`recipe`	No	a recipe id from hermoso_capabilities to force an archetype
`talent`	No	who is on camera; omit to follow the format. Say 'someone new' in product to skip reusing a saved creator.
`product`	Yes	what to advertise + any angle/offer the user specified
`setting`	No	force the WHERE — a setting id from list_hooks (e.g. "kitchen", "gym", or a surreal one like "volcano_rim" / "airplane_wing", which are played 100% straight and never acknowledged). Omit for a neutral setting.
`language`	No	output language for the ad copy (e.g. Spanish) — default English
`reference`	No	a reference to clone: an ad-library link (Facebook Ad Library, LinkedIn Ad Library, Google Ads Transparency — its real copy/advertiser are fetched) OR a VIDEO link — a TikTok, Instagram Reel, Facebook video, X post, YouTube Short/video or a direct video file — which is WATCHED first (frames + voiceover/on-screen-text transcript) so the concept keeps its hook, structure and pacing. To remake one video for this brand at its own length, clone_video is the direct tool
`durationSeconds`	No	VIDEO ONLY — the total spot length the user explicitly asked for, in seconds, copied verbatim (30 for "a 30 second ad"). The planner authors the storyboard TO it: the scenes’ seconds sum to it and the script is word-budgeted for it. Supported range 4–180; anything outside is CLAMPED to it (the reply says so). A length that fits ONE clip of the render model renders as a single continuous pass; anything longer is STITCHED from acts filled to that model’s clip maximum with the remainder last (on a 15s-clip model, 40 -> 15+15+10 and 17 -> 13+4) — never time-compressed. The maximum is the model’s own: 15s on most, 30s on the longest-clip model, so a 30s ad can be one unbroken take rather than two acts. Omit when the user named no length; do NOT pass a guess: an omitted value is the default, a 30s spot in one unbroken take (2026-09-29), and a length the user names always wins.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.1.366Oct 1, 2026

changedInput schema / properties / durationSeconds / description

Previous value: -"VIDEO ONLY — the total spot length the user explicitly asked for, in seconds, copied verbatim (30 for \"a 30 second ad\"). The planner authors the storyboard TO it: the scenes’ seconds sum to it and the script is word-budgeted for it. Supported range 4–180; anything outside is CLAMPED to it (the reply says so). A length that fits ONE clip of the render model renders as a single continuous pass; anything longer is STITCHED from acts filled to that model’s clip maximum with the remainder last (on a 15s-clip model, 40 -> 15+15+10 and 17 -> 13+4) — never time-compressed. The maximum is the model’s own: 15s on most, 30s on the longest-clip model, so a 30s ad can be one unbroken take rather than two acts. Omit when the user named no length; do NOT pass a guess, an omitted value keeps the recipe-aware default."New value: +"VIDEO ONLY — the total spot length the user explicitly asked for, in seconds, copied verbatim (30 for \"a 30 second ad\"). The planner authors the storyboard TO it: the scenes’ seconds sum to it and the script is word-budgeted for it. Supported range 4–180; anything outside is CLAMPED to it (the reply says so). A length that fits ONE clip of the render model renders as a single continuous pass; anything longer is STITCHED from acts filled to that model’s clip maximum with the remainder last (on a 15s-clip model, 40 -> 15+15+10 and 17 -> 13+4) — never time-compressed. The maximum is the model’s own: 15s on most, 30s on the longest-clip model, so a 30s ad can be one unbroken take rather than two acts. Omit when the user named no length; do NOT pass a guess: an omitted value is the default, a 30s spot in one unbroken take (2026-09-29), and a length the user names always wins."

addedInput schema / properties / talent

Added value: +{
+  "description": "who is on camera; omit to follow the format. Say 'someone new' in product to skip reusing a saved creator.",
+  "enum": [
+    "auto",
+    "creator",
+    "product_only"
+  ],
+  "type": "string"
+}

Changed2 schema fields changedv0.1.272Sep 23, 2026

addedInput schema / properties / draft

Added value: +{
+  "description": "ONLY after a video refusal that offered a light draft: the {model, durationSeconds} it named. The plan is then authored to that length and priced on that model. Never invent one — a video the account cannot cover is refused BEFORE planning with the three options (image / add credits / this draft when one fits), and the user chooses.",
+  "properties": {
+    "durationSeconds": {
+      "type": "number"
+    },
+    "model": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "model",
+    "durationSeconds"
+  ],
+  "type": "object"
+}

changedInput schema / properties / durationSeconds / description

Previous value: -"VIDEO ONLY — the total spot length the user explicitly asked for, in seconds, copied verbatim (30 for \"a 30 second ad\"). The planner authors the storyboard TO it: the scenes’ seconds sum to it and the script is word-budgeted for it. Supported range 4–180; anything outside is CLAMPED to it (the reply says so). A length that fits ONE clip of the render model renders as a single continuous pass; anything longer is STITCHED from acts filled to that model’s clip maximum with the remainder last (on a 15s-clip model, 40 → 15+15+10 and 17 → 13+4) — never time-compressed. The maximum is the model’s own: 15s on most, 30s on the longest-clip model, so a 30s ad can be one unbroken take rather than two acts. Omit when the user named no length; do NOT pass a guess, an omitted value keeps the recipe-aware default."New value: +"VIDEO ONLY — the total spot length the user explicitly asked for, in seconds, copied verbatim (30 for \"a 30 second ad\"). The planner authors the storyboard TO it: the scenes’ seconds sum to it and the script is word-budgeted for it. Supported range 4–180; anything outside is CLAMPED to it (the reply says so). A length that fits ONE clip of the render model renders as a single continuous pass; anything longer is STITCHED from acts filled to that model’s clip maximum with the remainder last (on a 15s-clip model, 40 -> 15+15+10 and 17 -> 13+4) — never time-compressed. The maximum is the model’s own: 15s on most, 30s on the longest-clip model, so a 30s ad can be one unbroken take rather than two acts. Omit when the user named no length; do NOT pass a guess, an omitted value keeps the recipe-aware default."

Changed1 schema field changedv0.1.227Sep 12, 2026

changedInput schema / properties / reference / description

Previous value: -"a reference to remix: an ad-library link (Facebook Ad Library, LinkedIn Ad Library, Google Ads Transparency — its real copy/advertiser are fetched) OR a VIDEO link — a TikTok, Instagram Reel, Facebook video, X post, YouTube Short/video or a direct video file — which is WATCHED first (frames + voiceover/on-screen-text transcript) so the concept keeps its hook, structure and pacing. To remake one video for this brand at its own length, clone_video is the direct tool"New value: +"a reference to clone: an ad-library link (Facebook Ad Library, LinkedIn Ad Library, Google Ads Transparency — its real copy/advertiser are fetched) OR a VIDEO link — a TikTok, Instagram Reel, Facebook video, X post, YouTube Short/video or a direct video file — which is WATCHED first (frames + voiceover/on-screen-text transcript) so the concept keeps its hook, structure and pacing. To remake one video for this brand at its own length, clone_video is the direct tool"

Changed1 schema field changedv0.1.225Sep 11, 2026

changedInput schema / properties / reference / description

Previous value: -"a reference ad URL to remix the angle from — Facebook Ad Library, LinkedIn Ad Library or Google Ads Transparency links (the real ad’s copy/advertiser are fetched and fed into the concept)"New value: +"a reference to remix: an ad-library link (Facebook Ad Library, LinkedIn Ad Library, Google Ads Transparency — its real copy/advertiser are fetched) OR a VIDEO link — a TikTok, Instagram Reel, Facebook video, X post, YouTube Short/video or a direct video file — which is WATCHED first (frames + voiceover/on-screen-text transcript) so the concept keeps its hook, structure and pacing. To remake one video for this brand at its own length, clone_video is the direct tool"

Changed4 schema fields changedv0.1.161Aug 27, 2026

addedInput schema / properties / durationSeconds

Added value: +{
+  "description": "VIDEO ONLY — the total spot length the user explicitly asked for, in seconds, copied verbatim (30 for \"a 30 second ad\"). The planner authors the storyboard TO it: the scenes’ seconds sum to it and the script is word-budgeted for it. Supported range 4–180; anything outside is CLAMPED to it (the reply says so). A length that fits ONE clip of the render model renders as a single continuous pass; anything longer is STITCHED from acts filled to that model’s clip maximum with the remainder last (on a 15s-clip model, 40 → 15+15+10 and 17 → 13+4) — never time-compressed. The maximum is the model’s own: 15s on most, 30s on the longest-clip model, so a 30s ad can be one unbroken take rather than two acts. Omit when the user named no length; do NOT pass a guess, an omitted value keeps the recipe-aware default.",
+  "type": "number"
+}

addedInput schema / properties / hook

Added value: +{
+  "description": "force the VISUAL scroll-stop mechanic the opening beat is built on — a hook id from list_hooks (e.g. \"direct_callout\", \"mid_problem\", \"macro_asmr\"). Omit to let the planner pick. A hook that cannot be delivered in this brief is DROPPED with the reason rather than rendered wrongly — an on-screen-text hook on an authentic/UGC ad is the one that bites, because that register carries zero on-screen text.",
+  "type": "string"
+}

addedInput schema / properties / setting

Added value: +{
+  "description": "force the WHERE — a setting id from list_hooks (e.g. \"kitchen\", \"gym\", or a surreal one like \"volcano_rim\" / \"airplane_wing\", which are played 100% straight and never acknowledged). Omit for a neutral setting.",
+  "type": "string"
+}

changedOutput schema / (root)

Previous value: -{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "additionalProperties": false,
-  "properties": {
-    "brand": {
-      "description": "the brand grounding embedded in the creative (name, logo, palette, productImages)"
-    },
-    "concept": {
-      "description": "the one-line creative concept",
-      "type": "string"
-    },
-    "copy": {
-      "description": "copy variants ({headline, primary, cta})",
-      "items": {},
-      "type": "array"
-    },
-    "format": {
-      "description": "the resolved creative format — 'image' or 'video'",
-      "type": "string"
-    },
-    "image_concept": {
-      "description": "the render-ready image concept (prompt etc.) when format is image"
-    },
-    "imodel": {
-      "description": "the image model id to render with",
-      "type": "string"
-    },
-    "recipe": {
-      "description": "the resolved recipe id",
-      "type": "string"
-    },
-    "recipe_label": {
-      "description": "the resolved recipe display name",
-      "type": "string"
-    },
-    "render_plan": {
-      "description": "the routing plan (structure/duration) render_ad honors"
-    },
-    "video_storyboard": {
-      "description": "the timed storyboard (scenes, cta, music) when format is video"
-    },
-    "vmodel": {
-      "description": "the video model id to render with",
-      "type": "string"
-    }
-  },
-  "type": "object"
-}New value: +null

Addedv0.1.15Jul 23, 2026
Removedv0.1.0Jul 22, 2026
First observedv0.1.0Jul 22, 2026

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds substantial behavior beyond annotations: 'Spends credits', 'Renders nothing', explicit duration-sovereignty rules, clamping outside 4–180s, scene-sum authoring, stitching math (40 -> 15+15+10, 17 -> 13+4), the model-clip-maximum constraint, and the hook-drop behavior. Annotations (destructiveHint=false, readOnlyHint=false, idempotentHint=false) only declare it as a non-idempotent, credit-spending writer; the description carries the real behavioral burden no annotation provides.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the purpose (concept, not a render) and the chaining requirement before diving into depth. It's dense but heavily load-bearing — the length/stitching passage is long because it's the tool's main correctness trap. The repeated emphasis on 'THE USER'S EXPLICIT LENGTH IS SOVEREIGN' is slightly redundant, keeping it just below 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 11 params (nested draft object, enums for format and talent), no output schema, and a credit-spending non-idempotent behavior, the description covers the essential traps: what it returns conceptually, why duration matters, when it refuses (video the account can't cover), and the chaining contract into render. No separate output schema means the description correctly stands in for the return-value shape.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 100%, but the description adds semantics the schema cannot: the duration itself is a sovereignty/consistency guarantee with clamping, sum-of-scenes authoring, and clip-stitching consequences, plus narrative on why omitting it silently yields a 15s spot. Other params equally get nuanced guidance (reference can be a link OR a watched video; hook is dropped with a reason if undeliverable).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('turn a brand + product/brief into a finished ad CONCEPT') and enumerates exactly what the output contains: copy variants (headline/primary/cta) plus an image_concept.prompt OR a video_storyboard, with the resolved recipe and model ids. It distinguishes itself from siblings immediately with 'Renders nothing; chain its output into generate_image / generate_video', separating it from render_ad, make_template_ad, generate_image, and generate_video.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use this tool and when not: it renders nothing and must be chained into generate_image / generate_video. It also names clone_video (via the reference param) and list_templates/list_hooks as prior steps, and explains the duration-choice condition ('leave it out and the planner picks its own default'). Alternatives and conditions are named rather than left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Plan an ad concept

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools