Skip to main content
Glama
Sign In

framesail

by com.framesail
OverviewDiscussions(1)Admin

Restructure a segment

segment_restructure
Destructive

Change what a segment is. No render is ever lost: what a change replaces goes to the bin.

combine: merge with a neighboring segment. The kept segment's prompts and renders stay over the combined length (a clip too short plays over its image; B-roll too short is refused); the other's go to the bin. Its sound effects and overlays join the kept segment.

change_type: to an image, real photo or B-roll (both fetched). Clips and talking heads come from render action=animate. keep_image turns a clip back into its image, keeping the render. The prompts carry over unchanged; render the segment again. A real photo or B-roll takes the searches it had before; one that had none gets them written by a small AI step in the background, which writes only its searches and spends credits (get_status wait=true); it renders once that finishes.

rewrite: an AI rewrite of the prompts from feedback, in the background: a small AI step that spends credits (get_status wait=true); render the image and clip again after. For exact text, use segment_edit set_prompts.

Sound effects and overlays always survive; change an overlay's text with editor_edit scene_note. Later segments may renumber: read the storyboard again.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "action": "<action>",
      "project_id": "<project_id>",
      "segment_number": "<segment_number>"
    },
    "name": "segment_restructure"
  }
}

Input Schema

NameRequiredDescriptionDefault
toNochange_type: the new kind
keepNocombine: whose prompts and renders survivethis
actionYescombine: with_segment_number, optional keep; change_type: to, optional keep_image; rewrite: feedback
feedbackNorewrite: what to change, e.g. "make this a close-up"
keep_imageNochange_type from a clip to image: keep the rendered image
project_idYesProject id
segment_numberYesSegment number (1-based, from storyboard_read)
with_segment_numberNocombine: the neighboring segment

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • removedInput schema / properties / confirm
      Removed value: -{
-  "default": false,
-  "description": "Run even though renders are lost; only after the user saw which",
-  "type": "boolean"
-}
    • changedInput schema / properties / to / anyOf
      Previous value: -[
-  {
-    "enum": [
-      "image",
-      "real_photo",
-      "b_roll",
-      "overlay_segment"
-    ],
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "enum": [
+      "image",
+      "real_photo",
+      "b_roll"
+    ],
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]
  2. Added

TDQS

A4.7/5.0
Behavior5/5

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

Annotations only flag destructive/not-idempotent; the description adds what is actually destroyed (replaced material goes to the bin), what survives (sound effects and overlays always survive; the kept segment keeps its prompts and renders), and that background AI steps spend credits and require get_status wait=true. That is far more than the annotations convey.

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?

Structure is strong — purpose first, then one block per action enum value, so it is easy to scan. Some parentheticals (clip-too-short / B-roll-too-short playback rules) are dense and could be trimmed, but nothing is truly wasted.

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

Completeness4/5

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

For an 8-parameter, destructive, non-idempotent tool with no output schema, the description covers all three modes, side effects, credit spend, and follow-up polling. It does not describe what the call returns or immediate error conditions beyond the clip-length rule, which is the remaining gap.

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, but the description adds real meaning beyond the terse schema strings: it explains that 'keep' decides whose prompts and renders survive, what 'to' values imply (clips/talking heads require render action=animate), and what keep_image preserves. It still leaves some parameters (feedback, with_segment_number) largely as the schema states them.

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 opening line names a specific verb and resource ('Change what a segment is') and the body distinguishes all three modes of the action enum (combine, change_type, rewrite) with concrete outcomes. It also separates itself from sibling tools by naming segment_edit and editor_edit where their behaviour differs.

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?

Each action gets an explicit when-to-use description, and the description routes away when this is the wrong tool: 'For exact text, use segment_edit set_prompts', 'change an overlay's text with editor_edit scene_note'. It also tells the agent to re-read the storyboard afterwards because segment numbers may shift.

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

All framesail toolsInspect
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