aicut

Regenerate one story frame

regenerate_story_frame

Destructive

Redraws ONE scene's opening picture of an episode parked at frames review (story.stage: "frames_review"), from the scene's own text, cast and continuity references. There is no prompt argument. WHEN: the user dislikes THE PICTURE itself (hands, framing, a face that came out wrong, a failed lane). scene_index is that frame's zero-based scene_index in get_video's story.frames. If what HAPPENS in the scene is wrong, a redraw only buys another picture of the same rejected beat: use change_story_scene. AFTER: returns image_id (status generating) and a report to RELAY as written (redrawn from the existing text; what happens, who is in frame and the spoken lines are unchanged). This call opens its own card with the scene marked as redrawing: no show_generation, no narrating the wait; poll get_video only to see the outcome (the lane's regenerate entry; the frame's url is then the new image). A failed redraw keeps the old frame. CHECK attached: false means the image is charged but will NOT replace the frame at fire: say so and redraw again before firing. cast_member_ids only when the user asks who is in the frame. COST: one standard image at the series' RESOLVED start-frame model (not the model the episode was created with, and not the discounted create rate): pricing.frame_regen_tokens on the series' full list_series entry (the series_id call), or estimate_only when null. State it every time: a standing go does not cover a redraw. THE GO THIS ONE NEEDS: one redraw, one named scene, one priced ask. A complaint ('scene 3 looks off') is a reason to OFFER it, never a go; never redraw more scenes than named. A redraw is not firing. SPENDS TOKENS: price with estimate_only: true, ask in the SAME message as the price, and wait for a go that names THIS purchase (SPENDING RULES, this server's instructions). IDEMPOTENCY: a reused idempotency_key REPLAYS the first job whatever the settings: never reuse one for a new generation (this server's instructions).

Input Schema

Name	Required	Description
`video_id`	Yes	The episode's job id from `generate_story_video`.
`scene_index`	Yes	The zero-based scene index exactly as `get_video`'s `story.frames` lists it (users count from ONE: 'redraw scene 2' is the SECOND frame).
`estimate_only`	No	Price only; creates nothing.
`cast_member_ids`	No	Cast member library ids for this redraw. Omit for the scene's own cast; `[]` for no characters.
`idempotency_key`	No	Retry-safety key (IDEMPOTENCY).

Schema Changelog

Changes observed during successful MCP inspections.

First observedOct 23, 2026

TDQS

A4.5/5.0

Behavior4/5

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

Annotations declare destructive/openWorld/idempotent=false, but the description adds substantial context beyond them: the cost source and that a standing go does not cover a redraw, the `attached: false` trap where the image is charged without replacing the frame, that a failed redraw keeps the old frame, that no card/polling narration is needed, and that a reused idempotency key replays the first job. Minor deduction only because cost/idempotency rules are restated across several sentences rather than stated once.

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

Conciseness3/5

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

Purpose and the when-to-use comparison are front-loaded, which is correct. However, the text is extremely dense with capitalized headers and repeats the spending/price rule ('State it every time', 'SPENDS TOKENS', 'THE GO THIS ONE NEEDS') in two places, so parts of it do not earn their space independently.

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?

No output schema exists, and the description fully compensates: it names the returned `image_id` with status `generating`, the `report` to relay verbatim, and how to confirm the outcome via `get_video`'s `regenerate` entry and the frame's new `url`. Cost, failure mode, and idempotency are all covered, so an agent can invoke this correctly end-to-end.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3; the description goes further by clarifying that `scene_index` maps to `get_video`'s `story.frames` (zero-based, users count from one) and bounding `cast_member_ids` to the 'user asks who is in the frame' case. It also flags the absence of a prompt argument, which prevents a common wrong invocation.

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?

States a specific verb and resource ('Redraws ONE scene's opening picture') plus the exact precondition (episode parked at `story.stage: "frames_review"`) and the source material. It explicitly distinguishes itself from `change_story_scene` by naming the alternative for a different failure mode.

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?

Provides an explicit WHEN clause with concrete triggers ('hands, framing, a face that came out wrong, a failed lane') and an explicit when-not routed to a sibling ('If what HAPPENS in the scene is wrong... use `change_story_scene`'). It also constrains scope ('never redraw more scenes than named') and clarifies that a complaint is an offer, not a go.

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

All aicut tools Inspect

Try in Browser