Skip to main content
Glama

framesail

by com.framesail
OverviewDiscussions(1)Admin

Director note (one scene)

director_note

Edit ONE scene with a natural-language note (the same director chat the editor UI uses): move/restyle/add/remove layers and overlays, change motion, etc. Storyboard image, video and voiceover layers can't be removed. Synchronous — returns summary, mutations, skipped_mutations (edits that did NOT land, with reasons — check it) and the scene's layers ({id, name, layerType, segmentAssetId}); list_scenes(include_composition=True) has the full composition. Address the scene by project_id + segment_number (preferred) or a scene_id from a fresh list_scenes call. Scene durations are locked to the narration: don't ask to extend/shorten any but the final scene. remove_segment_asset deletes an SFX or overlay by id without a model in the loop; for whole-video notes, project_director_note.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
messageYesNatural-language edit note for this scene, e.g. "move the caption to the top" or "calmer motion"
scene_idNoID of the scene to edit, from a FRESH list_scenes call — scene ids change whenever segments are edited (split/combine/update-content), so never reuse ids saved earlier; prefer project_id + segment_number
project_idNoProject ID; required (with segment_number) when not passing scene_id
segment_numberNo1-based segment number of the scene to edit (from list_scenes or get_segments) — preferred over scene_id because it is resolved to the current scene at call time
conversation_historyNoPrior chat turns as [{"role": ..., "content": ...}] to continue an editing conversation on this scene; omit to start fresh

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / message / description
      Previous value: -"Natural-language edit note for this scene, e.g. \"move the caption to the top\" or \"remove the overlay\""New value: +"Natural-language edit note for this scene, e.g. \"move the caption to the top\" or \"calmer motion\""
  2. Changed7 schema fields changed
    • addedInput schema / properties / project_id
      Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Project ID; required (with segment_number) when not passing scene_id",
+  "title": "Project Id"
+}
    • addedInput schema / properties / scene_id / anyOf
      Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]
    • addedInput schema / properties / scene_id / default
      Added value: +null
    • changedInput schema / properties / scene_id / description
      Previous value: -"ID of the scene to edit, from list_scenes"New value: +"ID of the scene to edit, from a FRESH list_scenes call — scene ids change whenever segments are edited (split/combine/update-content), so never reuse ids saved earlier; prefer project_id + segment_number"
    • removedInput schema / properties / scene_id / type
      Removed value: -"string"
    • addedInput schema / properties / segment_number
      Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "1-based segment number of the scene to edit (from list_scenes or get_segments) — preferred over scene_id because it is resolved to the current scene at call time",
+  "title": "Segment Number"
+}
    • changedInput schema / required
      Previous value: -[
-  "scene_id",
-  "message"
-]New value: +[
+  "message"
+]
  3. Changed3 schema fields changed
    • addedInput schema / properties / conversation_history / description
      Added value: +"Prior chat turns as [{\"role\": ..., \"content\": ...}] to continue an editing conversation on this scene; omit to start fresh"
    • addedInput schema / properties / message / description
      Added value: +"Natural-language edit note for this scene, e.g. \"move the caption to the top\" or \"remove the overlay\""
    • addedInput schema / properties / scene_id / description
      Added value: +"ID of the scene to edit, from list_scenes"
  4. First observed

TDQS

A4.9/5.0
Behavior5/5

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

Annotations are minimal (no readOnly/idempotent/destructive hints), so the description carries the full burden. It discloses that the call is synchronous, returns summary/mutations/skipped_mutations (with a warning to check skipped_mutations), and that scene ids change after segment edits – important behavioral context beyond annotations. No contradiction with annotations.

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

Conciseness5/5

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

The description is dense but every sentence earns its place: scope, exclusions, return behavior, addressing rules, duration constraint, and alternative tools. It front-loads the primary purpose and packs the rest efficiently without fluff.

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 mutation tool with five parameters and no output schema, the description covers all critical operational details: what can/can't be edited, return values and their significance, scene addressing, and when to use alternatives. Nothing 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 parameters are already documented. The description adds semantic value by explaining the preferred addressing method (project_id+segment_number) and why scene_id should come from a fresh list_scenes call (because ids become stale). This goes beyond the schema's basic descriptions.

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 opens with 'Edit ONE scene with a natural-language note' – a specific verb, resource, and mechanism. It enumerates example actions (move/restyle/add/remove layers, overlays, change motion) and distinguishes itself from siblings by explicitly naming project_director_note for whole-video notes and remove_segment_asset for direct deletions.

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?

It gives clear when-to-use and when-not-to-use guidance: 'for whole-video notes, project_director_note' and 'remove_segment_asset deletes an SFX or overlay by id without a model in the loop.' It also sets exclusions (storyboard/video/voiceover layers can't be removed) and a hard constraint (scene durations locked to narration, don't shorten/extend except final scene), plus how to address the scene (project_id+segment_number preferred, scene_id from a fresh list_scenes call).

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