Skip to main content
Glama
Sign In

ScreenWeaver

by ai.screenweaver
OverviewDiscussionsAdmin

Edit script

edit_script
Destructive

Edit the screenplay with structured operations, applied in order in one write. Live collaborators see the change immediately, and the pre-edit script is saved to version History so the user can undo it.

The script is a flat list of elements. Each element has a type and plain-text content:

  • SCENE_HEADING: "INT. KITCHEN - NIGHT" (optional placeId links a place entity)

  • ACTION: description of what happens

  • CHARACTER: the speaker's name before dialogue, optionally followed by a cue extension: "MARA" or "MARA (O.S.)" (optional characterId links a character entity). characterId links the name only: a linked line shows the entity's name followed by the extension. Pass extension ("O.S.", "V.O.", "CONT'D") instead of typing it into content if you prefer

  • DIALOGUE: the spoken line, right after CHARACTER (or PARENTHETICAL)

  • PARENTHETICAL: acting direction such as "(whispering)", between CHARACTER and DIALOGUE

  • TRANSITION: "CUT TO:"

  • SHOT: a camera shot line

  • Structure: EPISODE, ACT, SEQUENCE, STORY_BEAT (content is the title); OUTLINE is a note or the description of the structure element before it.

Operations:

  • insert: { op: "insert", afterElementId? | beforeElementId?, elements: [{ type, content, extension?, characterId?, placeId? }] }. With no anchor, elements are appended at the end of the script. New ids are created by the server and returned.

  • update: { op: "update", elementId, content?, type?, extension?, characterId?, placeId? }. null clears extension / characterId / placeId. extension is applied after content and replaces the extension already on the cue.

  • delete: { op: "delete", elementIds }. Any delete requires confirmDeletes: true; ask the user before deleting their writing.

Element ids come from get_scene or search_script; entity ids come from list_entities. Never invent ids: an unknown entity id, a characterId outside CHARACTER / DIALOGUE, or a placeId outside SCENE_HEADING is rejected, and so is an extension outside CHARACTER. Leave them unset when unsure: the app links CHARACTER names and scene headings to existing entities by name, and creates missing ones, when the project is open. A dialogue exchange is CHARACTER then DIALOGUE elements; a new scene starts with a SCENE_HEADING. Limits: 100 operations and 200 inserted elements per call; write a longer script in several calls, each inserting after the last element id the previous call returned. Final Draft (.fdx) and WriterDuet files go through import_script instead.

Input Schema

NameRequiredDescriptionDefault
projectIdYesScreenWeaver project id (from list_projects).
operationsYesEdit operations, applied in order.
confirmDeletesNoMust be true when any operation is a delete.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Goes well beyond the annotations (destructive/non-idempotent) by disclosing that live collaborators see changes immediately, that the pre-edit script is saved to version History for undo, that deletes require confirmDeletes:true, and the hard limits (100 ops, 200 elements per call). It also lists concrete rejection cases (unknown entity id, characterId outside CHARACTER/DIALOGUE, placeId outside SCENE_HEADING).

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 with the core action and organized into labeled sections (element types, operations, id sourcing, limits) so an agent can scan it. Nearly every sentence carries operationally relevant detail, though the element-type catalogue is dense enough to border on overload.

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?

With no output schema, the description compensates by stating that the server creates and returns new ids, and it covers the ordering guarantee, undo behavior, and per-call limits. For a complex multi-operation mutation tool this is complete enough to call correctly.

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 already 100%, so baseline is 3, but the description adds real semantic value: characterId links the name only (extension shown after it), pass extension rather than typing into content, null clears fields, and leaving ids unset lets the app auto-link/create entities by name. This meaningfully exceeds the schema documentation.

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?

States a specific verb (edit) and resource (the screenplay) and enumerates the exact operations supported (insert/update/delete) applied in order. It explicitly routes the .fdx/WriterDuet case to import_script, letting an agent separate it from that sibling without opening a 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?

Gives explicit conditions: use import_script for Final Draft (.fdx) and WriterDuet files, pull ids from get_scene/search_script and entities from list_entities, and ask the user before deleting. It also prescribes a concrete multi-call workflow for scripts exceeding the per-call limits.

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