@hubfluencer/mcp 0.14.0 → 0.15.0

package/README.md

@@ -113,7 +113,7 @@ instead draw a **free daily quota of 20 AI assists** (top up with `unlock_ai_ass
 | `generate_all_segments` | Render every not-yet-completed scene in order (continuity preserved); capped ~280s → re-run to continue. | **5 / segment** |
 | `set_narration_script` / `generate_narration` | Write your own voiceover script (free) **or** AI-draft one coherent script after every scene has completed with a known positive duration. AI drafting requires at least one scene without retained original audio and consumes an assist only when a fresh job is queued (exact retries dedupe for free). | free / 1 assist |
 | `generate_voice` | Synthesize the voiceover. `voice_id` required (see `list_voices`). | **3** |
-| `generate_music` | Generate background music (each call is a fresh take). | **5** |
+| `generate_music` | Generate background music (each call is a fresh take). Optional `instruments` is a string array (≤10 non-empty hints, ≤80 chars each), not a comma-separated string. | **5** |
 | `render` | Final MP4. Auto-charges and generates any pending or failed scenes first (4/scene in a batch of ≥3). | **0** |
 | `list_renders` | List every render version for an editor project (`id`, `version`, `status`, `video_url`, `thumbnail_url`, `duration_seconds`, `error_message`, `retryable`, `combination_hash`, `is_stale`, `inserted_at`) — find a failed render or recover a finished URL. | **0** |
 | `retry_render` | Re-run a **failed** render from its exact saved snapshot (recovery without re-driving the pipeline). | **0** |
@@ -137,19 +137,27 @@ images at **8 MiB (8,388,608 bytes)**; closing/short/catalog images at **20 MiB
 | `set_closing_image` | Set the ~2s end-card image (JPEG/PNG, ≤20 MiB; upload a file, or reuse the product image with `from_product:true`). |
 | `set_logo` | Upload a brand logo overlay (JPEG/PNG, ≤5 MiB; editor only; optional treatment/position/duration). |
 | `set_short_product` | Attach a product image (JPEG/PNG, ≤20 MiB) to a **short**. |
-| `set_short_logo` | Attach an exact deterministic logo overlay (JPEG/PNG, ≤5 MiB) to a **short**; choose its corner and `throughout`/`end_card`/`none` (hide) treatment. The logo is never sent to the video model. |
-| `set_short_poster` | Set a short's end-card poster (JPEG/PNG, ≤20 MiB; extends the render 12s → 14s). Pass `poster_includes_lockup:true` if the poster already carries brand name/CTA/badges — suppresses the overlaid claim/CTA so they don't collide. |
+| `set_short_logo` | Attach an exact deterministic logo overlay (JPEG/PNG, ≤5 MiB) to a **short**; choose its preferred corner and `throughout`/`end_card`/`none` (hide) treatment. Forge moves it away from text/CTA/chips. The logo is never sent to the video model. |
+| `set_short_poster` | Set a short's end-card poster (JPEG/PNG, ≤20 MiB; extends the render 12s → 14s). Phone-shaped portrait art is cover-cropped to 9:16; square, classic portrait, and landscape art is contained over a blurred backdrop. Pass `poster_includes_lockup:true` if the poster already carries brand name/CTA/badges — suppresses the overlaid claim/CTA and an end-card-only logo so they don't collide. |
 
 ### Status & delivery
 
 | Tool | What it does |
 |---|---|
-| `get_status` | Normalized `{stage, terminal, ready, video_url, error}` for a short / editor / tracking / slider. |
+| `get_status` | Normalized `{stage, terminal, ready, video_url, error}` for a short / editor / tracking / slider. While a paid short is rendering, also exposes `segments_completed`, `segments_total`, and `active_segment_positions`; `generation_attempt` is the cancellation fence. |
 | `wait_for_completion` | Block-poll until terminal (bounded ≤280s; returns `terminal:false` to re-call). `save_path` downloads the MP4 when ready. |
 | `download_result` | Get (or save, to `HUBFLUENCER_OUTPUT_DIR`) the finished MP4 URL. Not for sliders — use `get_slider`. |
-| `get_credits` / `list_voices` / `list_projects` | Credit balance; narration voices; recent projects (`include_completed:true` to recover a finished short's slug). |
+| `get_credits` / `list_voices` / `list_projects` | Credit balance; narration voices (including normalized verified `languages`); recent projects (`include_completed:true` to recover a finished short's slug). |
 | `get_ai_assists` / `unlock_ai_assists` | The free daily assist quota / spend 1 credit for +10. |
 
+### Creative export contract
+
+- Production prompts (`product_prompt`, `scenario_prompt`, and scene `prompt`) are visual directions. Narration scripts are read aloud verbatim, so `set_narration_script.script` must contain only the exact spoken words—never camera notes, prompt syntax, labels, or scene directions. Prefer `generate_narration` or Autopilot when exact wording is unnecessary.
+- Do not rely on the video model to spell essential brand names, UI, signs, prices, offers, or CTAs. Put exact copy in Hubfluencer overlays, narration, or supplied ending artwork.
+- `short_logo_position` is a preferred corner. Forge moves the logo away from headline, captions, CTA, offer, and badge areas. Use a tight transparent wordmark; use square/full-bleed art as the poster. `end_card` logos are suppressed when `poster_includes_lockup:true` to avoid double branding.
+- Short posters fill the ending frame: phone-shaped portrait art is cover-cropped, while square, classic portrait, and landscape art is contained over a blurred backdrop. Editor closing images are always cover-cropped. Keep important content in the central 9:16 safe area. An Editor closing image gets no generic CTA, so put the CTA in the artwork or state it in the preceding narration/scene.
+- Each Editor AI scene is 8 seconds. Request 3 scenes (about 24 seconds) for a concise social ad unless the brief needs a longer story.
+
 For editor projects, `video_url` may remain the last delivered MP4 after the timeline changes.
 It is current only when `ready:true` and `stale:false`. `stale:true` means the delivered render
 does not match the live timeline; regenerate the reported stale scenes/audio and render again.

package/dist/index.js

@@ -30266,7 +30266,7 @@ function readStoredCredentials() {
 // package.json
 var package_default = {
   name: "@hubfluencer/mcp",
-  version: "0.14.0",
+  version: "0.15.0",
   description: "Model Context Protocol server for Hubfluencer — let AI agents generate post-ready shorts and editor ads.",
   license: "MIT",
   author: "Monocursive <contact@monocursive.com>",
@@ -32140,7 +32140,7 @@ registerTool("get_credits", {
 }));
 registerTool("list_voices", {
   title: "List voices",
-  description: "Lists available narration voices (id + name). Pass a voice id as voice_id to create_editor_ad / " + "make_video to pick the narration voice for an editor ad. Shorts have no voiceover.",
+  description: "Lists available narration voices with voice_id, preview metadata, and verified language codes. " + "Choose a voice whose languages includes the editor project's language, then pass its voice_id to " + "create_editor_ad / make_video / generate_voice. Shorts have no voiceover.",
   inputSchema: {},
   annotations: { title: "List voices", ...RO }
 }, tool(async (_args, client) => {
@@ -32337,7 +32337,7 @@ registerTool("update_short", {
     brand_name: exports_external.string().max(40).optional().describe("Brand/product display name (≤40 chars) shown big on the closing brand-lockup slate when no " + `poster is set. Server falls back to your brand profile's name when unset. Pass "" to remove it.`),
     end_card: exports_external.enum(["auto", "none"]).optional().describe('"auto" (default): end on the poster, or on a brand-lockup slate (brand_name + claim + CTA pill) ' + 'when no poster is set — a 14s render. "none": no end card at all (12s, for deliberate ' + "loop-style shorts)."),
     poster_includes_lockup: exports_external.boolean().optional().describe("Set true if your poster already contains brand name/CTA/badges — suppresses the overlaid " + "claim/CTA so they don't collide (default false)."),
-    short_logo_position: exports_external.enum(["top-left", "top-right", "bottom-left", "bottom-right"]).optional().describe("Corner for the deterministic brand-logo overlay (set the image with set_short_logo). Moving it is " + "a FREE re-render — logo fields never cost credits."),
+    short_logo_position: exports_external.enum(["top-left", "top-right", "bottom-left", "bottom-right"]).optional().describe("Preferred corner for the deterministic brand-logo overlay (set the image with set_short_logo). " + "Forge moves it to a clear rail when text/CTA/chips occupy that corner. Moving it is a FREE " + "re-render — logo fields never cost credits."),
     short_logo_treatment: exports_external.enum(["throughout", "end_card", "none"]).optional().describe('When the brand logo shows: "throughout" the footage, only on the "end_card", or "none" to hide it. ' + "FREE re-render."),
     brand_profile_id: exports_external.number().int().optional().describe("Seed brand defaults — colors/font/CTA — from a saved brand profile (id from " + "list_brand_profiles). Best set at create_short time (that path also freezes a brand snapshot); " + "on update it sets the linked profile. Must be one of your own profiles.")
   },
@@ -32553,19 +32553,21 @@ registerTool("create_tracking_video", {
 }));
 registerTool("generate_short", {
   title: "Generate (render) a short",
-  description: "Deducts 15 credits and starts the render pipeline for an existing short — this RE-ROLLS the footage " + "and music (a fresh AI generation). For text/style/CTA/end-card tweaks on an already-generated short, " + "use rerender_short instead: it re-applies the overlay over the existing footage for 0 credits. " + "Safe to call again: a " + "duplicate while a render is in flight is reported as in-progress (no double charge), and a failed " + "short can be re-generated. If the draft's headline/subheadline/text_beats are all blank the server " + "auto-writes the headline + caption beats before rendering (pass skip_auto_text:true for a deliberately " + "bare clip). Then poll with get_status or wait_for_completion (kind=short).",
+  description: "Deducts 15 credits and starts the render pipeline for an existing short — this RE-ROLLS the footage " + "and music (a fresh AI generation). For text/style/CTA/end-card tweaks on an already-generated short, " + "use rerender_short instead: it re-applies the overlay over the existing footage for 0 credits. " + "Safe to call again: a " + "duplicate while a render is in flight is reported as in-progress (no double charge), and a failed " + "short can be re-generated. If the draft's headline/subheadline/text_beats are all blank the server " + "auto-writes the headline + caption beats before rendering (pass skip_auto_text:true for a deliberately " + "bare clip). A transient 5xx is reconciled against the project state: accepted work is returned as " + "in-progress, while an unchanged draft is retried once. Then poll with get_status or " + "wait_for_completion (kind=short).",
   inputSchema: {
     slug: exports_external.string().describe("Short slug from create_short"),
     skip_auto_text: exports_external.boolean().optional().describe("When the draft has no headline/subheadline/text_beats the server auto-writes the copy; pass " + "true to skip that and render a deliberately bare clip (default false).")
   },
   annotations: { title: "Generate short", ...WRITE }
 }, tool(async (args, client) => {
+  const submit = () => client.post(`/shorts/${args.slug}/generate`, args.skip_auto_text ? { skip_auto_text: true } : undefined);
   try {
-    const res = await client.post(`/shorts/${args.slug}/generate`, args.skip_auto_text ? { skip_auto_text: true } : undefined);
+    const res = await submit();
     const status = normalizeStatus("short", args.slug, asRecord(res).data);
     return ok(status);
   } catch (e) {
-    if (e.status === 409) {
+    const statusCode = e.status;
+    if (statusCode === 409) {
       return ok({
         kind: "short",
         slug: args.slug,
@@ -32576,6 +32578,35 @@ registerTool("generate_short", {
         error: null
       });
     }
+    if (statusCode !== undefined && statusCode >= 500) {
+      let reconciled;
+      try {
+        reconciled = await fetchStatus(client, "short", args.slug);
+      } catch (_reconcileError) {
+        throw e;
+      }
+      if (reconciled.stage === "rendering")
+        return ok(reconciled);
+      if (reconciled.stage !== "draft")
+        throw e;
+      try {
+        const retried = await submit();
+        return ok(normalizeStatus("short", args.slug, asRecord(retried).data));
+      } catch (retryError) {
+        if (retryError.status === 409) {
+          return ok({
+            kind: "short",
+            slug: args.slug,
+            stage: "processing",
+            terminal: false,
+            ready: false,
+            video_url: null,
+            error: null
+          });
+        }
+        throw retryError;
+      }
+    }
     throw e;
   }
 }));
@@ -32847,9 +32878,9 @@ registerTool("edit_slider_slide", {
 }));
 registerTool("create_editor_ad", {
   title: "Create, configure, and price a multi-scene editor ad",
-  description: "Creates an editor project, attaches any supplied local product/logo/closing assets BEFORE generation, " + "and prices autopilot (server-orchestrated " + "scenario → segments → narration → voice → music → render). Each AI-generated scene is a fixed 8 seconds. " + "Without max_credits it STOPS after the free draft/configuration and returns the live estimate. It starts " + "the paid pipeline only when max_credits is supplied and covers the estimate. Then poll with get_status / " + "wait_for_completion (kind=editor). Prefer make_video for a prompt-only one-shot. " + "A product image is analyzed into semantic project context and sent as a product-identity reference to every " + "generated Editor scene. The exact photo is also linked as the closing image unless a separate closing image " + "was authored; generated fine label text can still vary. Scene prompts are the complete content contract: describe any people, " + "products, visual continuity, absences, and composition directly in the brief. (Editor ads carry their copy " + "in-scene/narration, not as a title overlay; for an on-screen title/subtitle use a short with " + "headline/subheadline instead.)",
+  description: "Creates an editor project, attaches any supplied local product/logo/closing assets BEFORE generation, " + "and prices autopilot (server-orchestrated " + "scenario → segments → narration → voice → music → render). Each AI-generated scene is a fixed 8 seconds. " + "Without max_credits it STOPS after the free draft/configuration and returns the live estimate. It starts " + "the paid pipeline only when max_credits is supplied and covers the estimate. Then poll with get_status / " + "wait_for_completion (kind=editor). Prefer make_video for a prompt-only one-shot. " + "A product image is analyzed into semantic project context and sent as a product-identity reference to every " + "generated Editor scene. The exact photo is also linked as the closing image unless a separate closing image " + "was authored; generated fine label text can still vary. Do not depend on the video model for exact readable " + "brand names, UI, signs, prices, or CTA copy; put essential copy in narration or deterministic Short/poster overlays. " + "Scene prompts are the complete content contract: describe any people, " + "products, visual continuity, absences, and composition directly in the brief. (Editor ads carry their copy " + "in-scene/narration, not as a title overlay; for an on-screen title/subtitle use a short with " + "headline/subheadline instead.)",
   inputSchema: {
-    product_prompt: exports_external.string().min(10).describe("Brief for the ad (min 10 chars)"),
+    product_prompt: exports_external.string().min(10).describe("Creative brief for the ad (min 10 chars), not literal voiceover copy. Autopilot uses it to draft " + "narration. For exact spoken words, use the granular editor path and pass only read-aloud text to " + "set_narration_script."),
     product_subject: exports_external.string().max(300).optional().describe('The concrete product or main subject the video must be about (e.g. "Bordeaux red wine, dark green ' + 'bottle with a gold label"). Distinct from the freeform brief: hard-grounds the AI scenario + narration ' + "so it cannot invent an unrelated product. Strongly recommended for ads."),
     project_intent: exports_external.enum(["social_ad", "creative_story"]).optional().describe("social_ad for promotional/ad content (product focus + CTA), creative_story for brand narratives " + "(default)."),
     language: exports_external.enum(LANGUAGES).optional().describe('Language (default "en"). Bare ISO-639-1 code only — no region/script subtag (use "es", not "es-MX"). ' + "Drives the WHOLE video: scenario, narration script, narration voice, and captions. " + "Ask the user / infer from their locale."),
@@ -33628,7 +33659,7 @@ registerTool("generate_voice", {
 }));
 registerTool("generate_music", {
   title: "Generate the background music (5 credits)",
-  description: "Generates background music. Costs 5 credits. Each call produces a fresh take (music is non-deterministic) — call again for another. `description` is an optional" + "music-direction prompt (≤1200 chars; longer is silently truncated server-side). 402 fails cleanly.",
+  description: "Generates background music. Costs 5 credits. Each call produces a fresh take (music is non-deterministic) — call again for another. `description` is an optional" + " music-direction prompt (≤1200 chars; longer is silently truncated server-side). `instruments` is an " + "optional array of up to 10 non-empty hints (≤80 chars each), never a comma-separated string. 402 fails cleanly.",
   inputSchema: {
     slug: exports_external.string().describe("Editor project slug"),
     description: exports_external.string().max(1200).optional().describe("Music direction prompt (≤1200 chars, truncated if longer)"),
@@ -33984,11 +34015,11 @@ registerTool("set_short_product", {
 }));
 registerTool("set_short_logo", {
   title: "Set a Short brand logo overlay (0 credits)",
-  description: "Uploads an exact brand logo for deterministic compositing over a Short. The image is never sent to the " + "AI video provider, so lettering is preserved. PNG/JPEG, ≤5 MiB, 0 credits. Choose a corner and whether " + "it appears throughout the footage or only on the end card.",
+  description: "Uploads an exact brand logo for deterministic compositing over a Short. The image is never sent to the " + "AI video provider, so lettering is preserved. PNG/JPEG, ≤5 MiB, 0 credits. Choose a corner and whether " + "it appears throughout the footage or only on the end card. The corner is a preference: Forge moves the " + "logo to a clear rail when headline/caption/CTA/chip overlays occupy it. Prefer a tight transparent PNG " + "wordmark; use square/full-bleed artwork as a poster instead of a watermark.",
   inputSchema: {
     slug: exports_external.string().describe("Short slug"),
     file_path: exports_external.string().describe("Local logo image (.png/.jpg/.jpeg)"),
-    position: exports_external.enum(["top-left", "top-right", "bottom-left", "bottom-right"]).optional().describe("Logo corner (default top-right)"),
+    position: exports_external.enum(["top-left", "top-right", "bottom-left", "bottom-right"]).optional().describe("Preferred logo corner (default top-right; auto-relocated to avoid text)"),
     treatment: exports_external.enum(["throughout", "end_card", "none"]).optional().describe("When the logo appears (default throughout)")
   },
   annotations: { title: "Set Short logo", ...WRITE, idempotentHint: false }
@@ -34020,7 +34051,7 @@ registerTool("set_short_poster", {
 }));
 registerTool("get_status", {
   title: "Get generation status",
-  description: "Returns a normalized status {stage, terminal, ready, video_url, error} for a short, editor, " + "tracking, or slider project. ready:true means the post-ready MP4 is at video_url — except for a " + "slider (a carousel of stills, not a video): its video_url is always null, ready:true means every " + "slide is composited, and you read the per-slide image URLs with get_slider.",
+  description: "Returns a normalized status {stage, terminal, ready, video_url, error} for a short, editor, " + "tracking, or slider project. ready:true means the post-ready MP4 is at video_url — except for a " + "slider (a carousel of stills, not a video): its video_url is always null, ready:true means every " + "slide is composited, and you read the per-slide image URLs with get_slider. During paid short " + "generation, segments_completed / segments_total and active_segment_positions report real clip progress.",
   inputSchema: { slug: exports_external.string(), kind: kindSchema },
   outputSchema: getStatusOutput,
   annotations: { title: "Get status", ...RO }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hubfluencer/mcp",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Model Context Protocol server for Hubfluencer — let AI agents generate post-ready shorts and editor ads.",
   "license": "MIT",
   "author": "Monocursive <contact@monocursive.com>",

package/src/index.ts

@@ -1412,8 +1412,9 @@ registerTool(
 	{
 		title: "List voices",
 		description:
-			"Lists available narration voices (id + name). Pass a voice id as voice_id to create_editor_ad / " +
-			"make_video to pick the narration voice for an editor ad. Shorts have no voiceover.",
+			"Lists available narration voices with voice_id, preview metadata, and verified language codes. " +
+			"Choose a voice whose languages includes the editor project's language, then pass its voice_id to " +
+			"create_editor_ad / make_video / generate_voice. Shorts have no voiceover.",
 		inputSchema: {},
 		annotations: { title: "List voices", ...RO },
 	},
@@ -2023,8 +2024,9 @@ registerTool(
 				.enum(["top-left", "top-right", "bottom-left", "bottom-right"])
 				.optional()
 				.describe(
-					"Corner for the deterministic brand-logo overlay (set the image with set_short_logo). Moving it is " +
-						"a FREE re-render — logo fields never cost credits.",
+					"Preferred corner for the deterministic brand-logo overlay (set the image with set_short_logo). " +
+						"Forge moves it to a clear rail when text/CTA/chips occupy that corner. Moving it is a FREE " +
+						"re-render — logo fields never cost credits.",
 				),
 			short_logo_treatment: z
 				.enum(["throughout", "end_card", "none"])
@@ -2541,7 +2543,9 @@ registerTool(
 			"duplicate while a render is in flight is reported as in-progress (no double charge), and a failed " +
 			"short can be re-generated. If the draft's headline/subheadline/text_beats are all blank the server " +
 			"auto-writes the headline + caption beats before rendering (pass skip_auto_text:true for a deliberately " +
-			"bare clip). Then poll with get_status or wait_for_completion (kind=short).",
+			"bare clip). A transient 5xx is reconciled against the project state: accepted work is returned as " +
+			"in-progress, while an unchanged draft is retried once. Then poll with get_status or " +
+			"wait_for_completion (kind=short).",
 		inputSchema: {
 			slug: z.string().describe("Short slug from create_short"),
 			skip_auto_text: z
@@ -2563,17 +2567,21 @@ registerTool(
 		// of a failed short. Double-charge is prevented server-side — the batch
 		// claim's conditional update rolls back the losing transaction's credit
 		// deduction — and a 409 means a render is already running.
-		try {
-			const res = await client.post<{ data: unknown }>(
+		const submit = () =>
+			client.post<{ data: unknown }>(
 				`/shorts/${args.slug}/generate`,
 				// Only send a body when the caller opts out of server auto-copy —
 				// the bare POST stays byte-identical to the pre-0.8.2 wire shape.
 				args.skip_auto_text ? { skip_auto_text: true } : undefined,
 			);
+
+		try {
+			const res = await submit();
 			const status = normalizeStatus("short", args.slug, asRecord(res).data);
 			return ok(status);
 		} catch (e) {
-			if ((e as { status?: number }).status === 409) {
+			const statusCode = (e as { status?: number }).status;
+			if (statusCode === 409) {
 				return ok({
 					kind: "short",
 					slug: args.slug,
@@ -2584,6 +2592,47 @@ registerTool(
 					error: null,
 				});
 			}
+
+			if (statusCode !== undefined && statusCode >= 500) {
+				let reconciled: NormalizedStatus;
+				try {
+					reconciled = await fetchStatus(client, "short", args.slug);
+				} catch (_reconcileError) {
+					// Preserve the original POST failure when the read-side check also
+					// fails; the client must never blind-retry a possibly accepted debit.
+					throw e;
+				}
+
+				// Only the active render stage proves this POST crossed the paid
+				// launch transaction. A previous completed/failed result can still be
+				// visible after an early 5xx; returning it here would masquerade stale
+				// work as the newly accepted generation.
+				if (reconciled.stage === "rendering") return ok(reconciled);
+				if (reconciled.stage !== "draft") throw e;
+
+				// A Short launch changes the durable factory out of draft in the
+				// same transaction as the debit. Still-draft therefore proves the
+				// failed response accepted no paid work, so one retry is safe.
+				try {
+					const retried = await submit();
+					return ok(
+						normalizeStatus("short", args.slug, asRecord(retried).data),
+					);
+				} catch (retryError) {
+					if ((retryError as { status?: number }).status === 409) {
+						return ok({
+							kind: "short",
+							slug: args.slug,
+							stage: "processing",
+							terminal: false,
+							ready: false,
+							video_url: null,
+							error: null,
+						});
+					}
+					throw retryError;
+				}
+			}
 			throw e;
 		}
 	}),
@@ -3131,7 +3180,9 @@ registerTool(
 			"wait_for_completion (kind=editor). Prefer make_video for a prompt-only one-shot. " +
 			"A product image is analyzed into semantic project context and sent as a product-identity reference to every " +
 			"generated Editor scene. The exact photo is also linked as the closing image unless a separate closing image " +
-			"was authored; generated fine label text can still vary. Scene prompts are the complete content contract: describe any people, " +
+			"was authored; generated fine label text can still vary. Do not depend on the video model for exact readable " +
+			"brand names, UI, signs, prices, or CTA copy; put essential copy in narration or deterministic Short/poster overlays. " +
+			"Scene prompts are the complete content contract: describe any people, " +
 			"products, visual continuity, absences, and composition directly in the brief. (Editor ads carry their copy " +
 			"in-scene/narration, not as a title overlay; for an on-screen title/subtitle use a short with " +
 			"headline/subheadline instead.)",
@@ -3139,7 +3190,11 @@ registerTool(
 			product_prompt: z
 				.string()
 				.min(10)
-				.describe("Brief for the ad (min 10 chars)"),
+				.describe(
+					"Creative brief for the ad (min 10 chars), not literal voiceover copy. Autopilot uses it to draft " +
+						"narration. For exact spoken words, use the granular editor path and pass only read-aloud text to " +
+						"set_narration_script.",
+				),
 			product_subject: z
 				.string()
 				.max(300)
@@ -4806,7 +4861,8 @@ registerTool(
 		title: "Generate the background music (5 credits)",
 		description:
 			"Generates background music. Costs 5 credits. Each call produces a fresh take (music is non-deterministic) — call again for another. `description` is an optional" +
-			"music-direction prompt (≤1200 chars; longer is silently truncated server-side). 402 fails cleanly.",
+			" music-direction prompt (≤1200 chars; longer is silently truncated server-side). `instruments` is an " +
+			"optional array of up to 10 non-empty hints (≤80 chars each), never a comma-separated string. 402 fails cleanly.",
 		inputSchema: {
 			slug: z.string().describe("Editor project slug"),
 			description: z
@@ -5594,14 +5650,18 @@ registerTool(
 		description:
 			"Uploads an exact brand logo for deterministic compositing over a Short. The image is never sent to the " +
 			"AI video provider, so lettering is preserved. PNG/JPEG, ≤5 MiB, 0 credits. Choose a corner and whether " +
-			"it appears throughout the footage or only on the end card.",
+			"it appears throughout the footage or only on the end card. The corner is a preference: Forge moves the " +
+			"logo to a clear rail when headline/caption/CTA/chip overlays occupy it. Prefer a tight transparent PNG " +
+			"wordmark; use square/full-bleed artwork as a poster instead of a watermark.",
 		inputSchema: {
 			slug: z.string().describe("Short slug"),
 			file_path: z.string().describe("Local logo image (.png/.jpg/.jpeg)"),
 			position: z
 				.enum(["top-left", "top-right", "bottom-left", "bottom-right"])
 				.optional()
-				.describe("Logo corner (default top-right)"),
+				.describe(
+					"Preferred logo corner (default top-right; auto-relocated to avoid text)",
+				),
 			treatment: z
 				.enum(["throughout", "end_card", "none"])
 				.optional()
@@ -5700,7 +5760,8 @@ registerTool(
 			"Returns a normalized status {stage, terminal, ready, video_url, error} for a short, editor, " +
 			"tracking, or slider project. ready:true means the post-ready MP4 is at video_url — except for a " +
 			"slider (a carousel of stills, not a video): its video_url is always null, ready:true means every " +
-			"slide is composited, and you read the per-slide image URLs with get_slider.",
+			"slide is composited, and you read the per-slide image URLs with get_slider. During paid short " +
+			"generation, segments_completed / segments_total and active_segment_positions report real clip progress.",
 		inputSchema: { slug: z.string(), kind: kindSchema },
 		outputSchema: getStatusOutput,
 		annotations: { title: "Get status", ...RO },