Skip to main content
Glama
Sign In

ScreenWeaver

by ai.screenweaver
OverviewDiscussionsAdmin

Add reference images

add_reference_images

Add stored images to groups as image nodes and connect each one to a node of its group, exactly like dropping the files into the group and connecting them in the app: the image's @# token is appended to the node's text. One call takes up to 25 groups (items), e.g. every shot of a scene with its board crops; each group appears once. Everything is checked before anything is written, then written at once. Default target per group (defaultNodeId in get_group): a shot's panel generator ({ kind: "shot", id }), the starred generator of a shot's production group or the art direction, and for a story element ({ kind: "story_element", id, group }) its reference sheet generator (storyboard, the default group) or its production reference generator (production), whose prompt then cites the images; in a story element's moodboard, its Story element node. nodeId picks another generator or text node of the group; nodes the app would not connect an image to are refused. Name the Story element node ({entityId}-story-element) only to change what every shot citing the element receives: board crops there reach every shot, other shots' boards included. mediaIds come from import_media (pages and crops) or from get_group / view_media. An image already in the group is reused, so calling again does not duplicate it. Returns each image's nodeId and token: cite them in the prompt you write next. wired and connectedToRole say which node the images were connected to (shot_panel, reference_sheet, production_reference, story_element_stage, art_direction, generator, text): report that to the user. The token alone does not tell a generator what to do with the image: when it is a reference the user gave a purpose for, rewrite the prompt with set_prompt in the same run. A shot's boards go in create_shots / update_shot attachments instead, which keep the panel on the app's board template (see the storyboard guide); added here, they make the panel prompt a written one. A model takes a limited number of reference images: the call fails without writing anything when a generator's prompt would cite more. No images are generated and no credits are spent.

Input Schema

NameRequiredDescriptionDefault
itemsYesOne entry per group (max 25), e.g. every shot of a scene with its boards. Each group can appear once.
projectIdYesScreenWeaver project id (from list_projects).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / items / items / properties / nodeId / description
      Previous value: -"A node of the group from get_group (nodeId): a generator, a text node or the Story element node. Omit for the group's default target (defaultNodeId in get_group): a shot's panel, the starred generator of a production group or the art direction, a story element's Story element node."New value: +"A node of the group from get_group (nodeId): a generator, a text node or the Story element node. Omit for the group's default target (defaultNodeId in get_group): a shot's panel, the starred generator of a production group or the art direction, a story element's reference sheet generator (storyboard) or production reference generator (production), and a story element's Story element node in its moodboard. Name the Story element node ({entityId}-story-element) only to change what every shot citing the element receives."
  2. Changed5 schema fields changed
    • addedInput schema / properties / items
      Added value: +{
+  "description": "One entry per group (max 25), e.g. every shot of a scene with its boards. Each group can appear once.",
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "mediaIds": {
+        "description": "Images to add to this group, as media ids from import_media, view_media or get_group (max 8), e.g. a board's panel crop and the strip of the whole shot.",
+        "items": {
+          "maxLength": 200,
+          "minLength": 1,
+          "type": "string"
+        },
+        "maxItems": 8,
+        "minItems": 1,
+        "type": "array"
+      },
+      "nodeId": {
+        "description": "A node of the group from get_group (nodeId): a generator, a text node or the Story element node. Omit for the group's default target (defaultNodeId in get_group): a shot's panel, the starred generator of a production group or the art direction, a story element's Story element node.",
+        "maxLength": 200,
+        "minLength": 1,
+        "type": "string"
+      },
+      "target": {
+        "additionalProperties": false,
+        "description": "The group, e.g. { kind: \"shot\", id: shotId } for a shot's panel group, { kind: \"story_element\", id: entityId } for a reference sheet, { kind: \"art_direction\" }.",
+        "properties": {
+          "group": {
+            "description": "Which group. A shot has storyboard (its panel) and production; a story element has moodboard, storyboard (its reference sheet) and production. Defaults to storyboard. Ignored for the art direction.",
+            "enum": [
+              "moodboard",
+              "storyboard",
+              "production"
+            ],
+            "type": "string"
+          },
+          "id": {
+            "description": "shotId (list_shots) for a shot, entityId (list_entities) for a story element. Omit for the art direction.",
+            "maxLength": 128,
+            "minLength": 1,
+            "type": "string"
+          },
+          "kind": {
+            "description": "shot (a shot's storyboard or production group), story_element (a character, place or object's moodboard, storyboard or production group) or art_direction (the project's art direction).",
+            "enum": [
+              "shot",
+              "story_element",
+              "art_direction"
+            ],
+            "type": "string"
+          }
+        },
+        "required": [
+          "kind"
+        ],
+        "type": "object"
+      }
+    },
+    "required": [
+      "target",
+      "mediaIds"
+    ],
+    "type": "object"
+  },
+  "maxItems": 25,
+  "minItems": 1,
+  "type": "array"
+}
    • removedInput schema / properties / mediaIds
      Removed value: -{
-  "description": "Images to add, as media ids from import_media, view_media or get_group (max 8).",
-  "items": {
-    "maxLength": 200,
-    "minLength": 1,
-    "type": "string"
-  },
-  "maxItems": 8,
-  "minItems": 1,
-  "type": "array"
-}
    • removedInput schema / properties / nodeId
      Removed value: -{
-  "description": "A node of the group from get_group (nodeId): a generator, a text node or the Story element node. Omit for the group's default target (defaultNodeId in get_group): a shot's panel, the starred generator of a production group or the art direction, a story element's Story element node.",
-  "maxLength": 200,
-  "minLength": 1,
-  "type": "string"
-}
    • removedInput schema / properties / target
      Removed value: -{
-  "additionalProperties": false,
-  "description": "The group, e.g. { kind: \"shot\", id: shotId } for a shot's panel group, { kind: \"story_element\", id: entityId } for a reference sheet, { kind: \"art_direction\" }.",
-  "properties": {
-    "group": {
-      "description": "Which group. A shot has storyboard (its panel) and production; a story element has moodboard, storyboard (its reference sheet) and production. Defaults to storyboard. Ignored for the art direction.",
-      "enum": [
-        "moodboard",
-        "storyboard",
-        "production"
-      ],
-      "type": "string"
-    },
-    "id": {
-      "description": "shotId (list_shots) for a shot, entityId (list_entities) for a story element. Omit for the art direction.",
-      "maxLength": 128,
-      "minLength": 1,
-      "type": "string"
-    },
-    "kind": {
-      "description": "shot (a shot's storyboard or production group), story_element (a character, place or object's moodboard, storyboard or production group) or art_direction (the project's art direction).",
-      "enum": [
-        "shot",
-        "story_element",
-        "art_direction"
-      ],
-      "type": "string"
-    }
-  },
-  "required": [
-    "kind"
-  ],
-  "type": "object"
-}
    • changedInput schema / required
      Previous value: -[
-  "target",
-  "mediaIds",
-  "projectId"
-]New value: +[
+  "items",
+  "projectId"
+]
  3. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Adds substantial context beyond the annotations: validate-then-write atomicity ('Everything is checked before anything is written, then written at once'), a hard failure with no writes when a generator would cite too many references, no image generation or credit spend, node-text token appending, and reuse of already-present images. It also documents the return payload (nodeId, token, wired, connectedToRole) since no output schema exists. Minor nuance: 'calling again does not duplicate it' sits slightly against idempotentHint=false, but the hint concerns the whole call (wiring/token writes), not image dedupe, so this reads as clarification rather than contradiction.

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?

Well front-loaded — purpose first, then targets, then follow-up — but the body is a dense ~350-word block for a two-parameter tool, and the defaultNodeId resolution rules are restated almost verbatim from the nodeId schema description. It is informative rather than wasteful, but the duplication and clause chaining cost it conciseness.

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 no output schema, the definition covers atomicity, failure conditions, return fields, and required follow-up (set_prompt) — everything an agent needs to call it and act on the result correctly.

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

Parameters5/5

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

Schema coverage is already 100%, yet the description still adds decision-relevant meaning: how target kinds resolve to default nodes (shot panel generator, starred generator, art direction, story element reference sheet vs production reference), when nodeId should be omitted versus set, and where mediaIds come from. This is meaning beyond field descriptions, not repetition.

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 first sentence states a specific verb and resource — adding stored images to groups as image nodes and wiring each to a node — and immediately differentiates itself from the sibling path: shot boards belong in create_shots/update_shot attachments instead. An agent can identify the tool's job from the opening sentence alone.

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 is given for alternatives: use create_shots/update_shot attachments for shot boards, import_media/get_group/view_media for mediaIds, set_prompt afterward when the image has a user-stated purpose. It also states exclusions (nodes the app would not connect an image to are refused; name the Story element node only to change what every citing shot receives).

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