Skip to main content
Glama
Sign In

ScreenWeaver

by ai.screenweaver
OverviewDiscussionsAdmin

Create shots

create_shots

Create storyboard shots in one scene of the project, in order, in a single write. Live collaborators see them immediately. The project needs an aspect ratio first: when get_project_outline shows aspectRatio null, ask the user which one and call set_project_aspect_ratio. Use it to turn director's notes or a shot list into shots: read the scene first (get_scene) and take sceneId from get_project_outline or get_scene; call list_shots to see existing shots and their shotIds. Each shot needs an actionText and may set shotValue (framing), cameraMovement and durationSeconds; unspecified fields keep the app defaults. Set continuesFrom to chain a shot onto an earlier one (index in this call, or an existing shotId of the scene). A continuation inherits the framing and camera of its chain head, so do not rely on its own shotValue/cameraMovement. A shot that is not a continuation and does not already show a place gets the scene heading's place appended to its actionText, so the storyboard image keeps the location. When boards, comic panels or pages stand for the shots, give each shot its attachments (board crops, and context such as the strip of the whole shot) in this same call: the panel prompt then follows the boards on the app's board template, with no prompt to write (see the storyboard guide). boardInstructions applies to every shot of the call. No images are generated and no credits are spent. Returns createdShotIds (same order as the input), the scene's shots after the write, and per shot with attachments what was attached and which panel prompt it has; check them. Max 50 shots per call.

Input Schema

NameRequiredDescriptionDefault
shotsYesThe shots to create, in storyboard order (max 50).
sceneIdYesScene to add the shots to (sceneId from get_project_outline or get_scene).
projectIdYesScreenWeaver project id (from list_projects).
boardInstructionsNoWhat the redraw of the boards must do or leave out beyond the template, in the user's words, e.g. "Leave out the camera arrows; keep the rain." Only when the user asked for something. Never cite the art direction.
insertAfterShotIdNoPlace the new shots right after this existing shot of the same scene (shotId from list_shots). Omit to append at the end of the scene.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • addedInput schema / properties / boardInstructions
      Added value: +{
+  "description": "What the redraw of the boards must do or leave out beyond the template, in the user's words, e.g. \"Leave out the camera arrows; keep the rain.\" Only when the user asked for something. Never cite the art direction.",
+  "maxLength": 2000,
+  "minLength": 1,
+  "type": "string"
+}
    • changedInput schema / properties / shots / items / properties / actionText / description
      Previous value: -"What the frame shows and what happens in it, as a concrete visual description for the storyboard image. To show a Story element (character, place, object) write its referenceHandle from list_entities, e.g. @ref_storyboard_char_alice_sheet for the character Alice. The server turns known handles into live references (they read back as @#<entityId>-story-element); unknown ones stay as plain text. Read-back @# tokens can be sent again unchanged. Describe the shot in story terms only, with no instruction to the generator (not \"Redraw board panel 3: …\" or \"keep the board's framing\"): the action also feeds the production and video prompts. Instructions about boards go in the panel prompt (set_prompt)."New value: +"What the frame shows and what happens in it, as a concrete visual description for the storyboard image. To show a Story element (character, place, object) write its referenceHandle from list_entities, e.g. @ref_storyboard_char_alice_sheet for the character Alice. The server turns known handles into live references (they read back as @#<entityId>-story-element); unknown ones stay as plain text. Read-back @# tokens can be sent again unchanged. Describe the shot in story terms only, with no instruction to the generator (not \"Redraw board panel 3: …\" or \"keep the board's framing\"): the action also feeds the production and video prompts. Boards go in attachments, and what to leave out of them in boardInstructions."
    • addedInput schema / properties / shots / items / properties / attachments
      Added value: +{
+  "description": "Images attached to the shot's panel, placed in its storyboard group (max 8). With a reference board the app's panel prompt switches to its board template: it cites the boards, the context images and the shot's action, framing and camera (so it follows later edits of them), takes identity from the story elements the action cites, and leaves out speech bubbles, lettering, arrows and notes. Write no panel prompt for it.",
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "mediaId": {
+        "description": "The image, as a media id from import_media (a page or a crop), view_media or get_group.",
+        "maxLength": 200,
+        "minLength": 1,
+        "type": "string"
+      },
+      "mode": {
+        "description": "Board only. reference (default): the panel generator redraws the board in the storyboard style, keeping its staging, with the story elements' look. as-is: the board itself becomes the shot's selected panel, as set_shot_panel does (at most one per shot).",
+        "enum": [
+          "reference",
+          "as-is"
+        ],
+        "type": "string"
+      },
+      "role": {
+        "description": "board: the drawing of this shot's frame. context: material the panel reads but does not draw, such as the strip of the whole shot or a page with the director's notes.",
+        "enum": [
+          "board",
+          "context"
+        ],
+        "type": "string"
+      }
+    },
+    "required": [
+      "mediaId",
+      "role"
+    ],
+    "type": "object"
+  },
+  "maxItems": 8,
+  "minItems": 1,
+  "type": "array"
+}
  2. Changed1 schema field changed
    • changedInput schema / properties / shots / items / properties / actionText / description
      Previous value: -"What the frame shows and what happens in it, as a concrete visual description for the storyboard image. To show a Story element (character, place, object) write its referenceHandle from list_entities, e.g. @ref_storyboard_char_alice_sheet for the character Alice. The server turns known handles into live references (they read back as @#<entityId>-story-element); unknown ones stay as plain text. Read-back @# tokens can be sent again unchanged."New value: +"What the frame shows and what happens in it, as a concrete visual description for the storyboard image. To show a Story element (character, place, object) write its referenceHandle from list_entities, e.g. @ref_storyboard_char_alice_sheet for the character Alice. The server turns known handles into live references (they read back as @#<entityId>-story-element); unknown ones stay as plain text. Read-back @# tokens can be sent again unchanged. Describe the shot in story terms only, with no instruction to the generator (not \"Redraw board panel 3: …\" or \"keep the board's framing\"): the action also feeds the production and video prompts. Instructions about boards go in the panel prompt (set_prompt)."
  3. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only cover the safety profile, and the description adds substantial context beyond them: collaborators see the write immediately, no images are generated and no credits are spent, max 50 shots per call, unspecified fields keep app defaults, and — most valuable — a non-continuation shot with no place silently gets the scene heading's place appended to its actionText. It also describes the return payload (createdShotIds in input order, the scene's shots, per-shot attachment outcomes) and tells the agent to check it.

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?

Purpose and collaborator-visibility are front-loaded, and the sequencing prerequisites follow immediately. The prose is dense but nearly every sentence carries a non-obvious rule; the board-template paragraph could be shortened since the schema already explains the template switch.

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 complex batch-mutation tool with no output schema, the description covers prerequisites, ordering, defaults, chaining inheritance, attachment roles, board instructions, limits and return shape. Nothing an agent needs to invoke it correctly across the happy path and the continuation/attachment edge cases 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 description coverage is already 100%, so the baseline is 3, but the description adds genuine semantics the schema does not: a continuation inherits the chain head's framing and camera so its own shotValue/cameraMovement are unreliable, and boardInstructions applies to every shot in the call. It stops short of clarifying insertAfterShotId's interaction with continuesFrom indexes.

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 sentence names a specific verb and resource ('Create storyboard shots'), the scope ('in one scene of the project, in order, in a single write'), and the batch semantics. An agent can tell this apart from update_shot, delete_shots and list_shots 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?

Explicit routing: read the scene first with get_scene, take sceneId from get_project_outline or get_scene, call list_shots for existing shotIds. It also states a hard prerequisite with a named alternative (when aspectRatio is null, ask the user and call set_project_aspect_ratio) and the intended use case (turn director's notes or a shot list into shots).

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

All ScreenWeaver 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