framesail

Restructure a segment

segment_restructure

Destructive

Change what a segment is. Every call previews first: when no rendered image or clip would be lost it runs; otherwise it changes nothing and returns what would be lost. Show the user, then call again with confirm=true.

combine: merge with a neighboring segment. The kept segment's renders stay, retimed to the combined length, but go stale: its prompts are rewritten for the combined narration, so render it again after. The other's are deleted (the preview names it).

change_type: to an image, real photo, B-roll (both fetched) or overlay segment. Clips and talking heads come from render action=animate. keep_image turns a clip back into its image, keeping the render. A change between an image, real photo and B-roll keeps the prompts; render the image again.

rewrite: an AI rewrite of the prompts from feedback; render the image and clip again after. For exact text, use segment_edit set_prompts.

combine, rewrite and a change to or from an overlay segment write prompts in the background, and a change to a real photo or B-roll with no searches yet writes its searches (its prompts stay): a small AI step that spends credits (get_status wait=true). Until it finishes, change_type is refused (409). Sound effects and overlays always survive; change an overlay's text with editor_edit scene_note. Later segments may renumber: read the storyboard again.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`to`	No	change_type: the new kind
`keep`	No	combine: whose prompts and renders survive	this
`action`	Yes	combine: with_segment_number, optional keep; change_type: to, optional keep_image; rewrite: feedback
`confirm`	No	Run even though renders are lost; only after the user saw which
`feedback`	No	rewrite: what to change, e.g. "make this a close-up"
`keep_image`	No	change_type from a clip to image: keep the rendered image
`project_id`	Yes	Project id
`segment_number`	Yes	Segment number (1-based, from storyboard_read)
`with_segment_number`	No	combine: the neighboring segment

Schema Changelog

Changes observed during successful MCP inspections.

AddedOct 1, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Far exceeds the annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=false): it discloses the preview-first contract, the confirm=true gate, the 409 refusal while background AI runs, credit spend, what renders survive or go stale, retiming of kept renders, and renumbering of later segments.

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?

Long but front-loaded: the preview/confirm workflow comes first before per-action detail. Each paragraph is organized by action and every sentence carries operational content, though the density is close to the upper limit of comfortable scanning.

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?

For a 9-parameter destructive mutation with no output schema, the description covers the preview return ('returns what would be lost'), the refusal mode, async background steps, credit cost, and downstream effects. Little an agent needs to call it correctly is missing.

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 schema already documents each parameter, giving a baseline of 3. The description adds genuine meaning on top: what 'keep' means for surviving prompts/renders and staleness, and what keep_image preserves when converting a clip back to an image.

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?

Opens with a specific verb+resource scoped to a single segment, then names and defines its three sub-actions (combine, change_type, rewrite). An agent can distinguish it from sibling segment_edit or render without opening any schema.

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 routes across alternatives: exact text goes to segment_edit set_prompts, clips/talking heads come from render action=animate, overlay text goes to editor_edit scene_note, and renumbering requires re-reading the storyboard. It also states the when-to-confirm condition ('only after the user saw which').

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

All framesail tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?