Skip to main content
Glama
Sign In

ScreenWeaver

by ai.screenweaver
OverviewDiscussionsAdmin

Import script file

import_script
Destructive

Import a Final Draft (.fdx) file, a WriterDuet (.json) file, or Fountain / screenplay-formatted plain text (a pasted script) into the project's script. Pass the full text as content, or the textId extract_file_text returned for a PDF or page images. The format is detected from the content; pass format only to force it ("fountain" forces the plain-text importer). Plain text counts as a screenplay when it has INT./EXT. scene headings or uppercase character cues with dialogue below them.

Call it with dryRun: true first. Nothing is written. The preview lists the scenes, element counts, where the content goes (and whether a Final Draft title page is kept), and for each character and place name in the file the entity it links to or "create", with near-miss candidates (a similar existing name, for example TOBY and TOBIAS). When the preview has names to create or near misses, show the user those links and ask. Then import for real with entityMap, mapping each confirmed name to its entityId (from the preview or list_entities). Names left out of entityMap are linked by name or created.

entityMap keys are names as the file writes them; a cue extension is ignored ("MARA (O.S.)" is the key "MARA"). Only characters and places can be mapped. A mapped cue line takes the entity's name and keeps its extension, and a mapped scene heading takes the place's name.

The file is parsed by the app's own importers: scene headings, action, characters, dialogue, parentheticals, transitions and structure keep their types. CHARACTER lines and scene headings are linked to the project's characters and places by name ("MARA (O.S.)" and "MARA (CONT'D)" link to MARA and keep "(O.S.)" / "(CONT'D)" on the cue line), and missing ones are created as story elements (returned in createdEntities). The pre-import script is saved to version History so the user can undo it.

insertPosition: "end" (default) appends after the current script; "start" puts the file first, after the script's title block (its first EPISODE and the OUTLINE lines under it); "replace" replaces the whole script and requires confirmReplace: true on the real call (a dryRun does not), so ask the user before replacing their writing. A Final Draft or Fountain title page becomes the script's title block only on a replace or an empty script; otherwise it is left out.

A PDF, a scan or photos of pages: call extract_file_text first, then import its text here with textId. Never retype a long script with edit_script. For text that is not screenplay-formatted (notes, prose), do not use this tool: write it with edit_script, one element per scene heading, action paragraph, character cue, parenthetical and dialogue line.

Input Schema

NameRequiredDescriptionDefault
dryRunNoPreview only: parse and plan, write nothing, and return the links the import would make.
formatNoForce the importer. Detected from content when omitted.
textIdNotextId from extract_file_text: imports that text instead of content.
contentNoThe file's full text: FDX XML, WriterDuet JSON, or Fountain / screenplay-formatted plain text. Pass this or textId.
entityMapNoForce links: { "<name in the file>": "<entityId of an existing character or place>" }. A cue extension in the key is ignored.
projectIdYesScreenWeaver project id (from list_projects).
confirmReplaceNoMust be true when insertPosition is "replace" (not needed with dryRun).
insertPositionNoWhere the imported script goes. Default end.end

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?

Annotations already flag destructiveHint=true and idempotentHint=false, but the description adds substantial behavioral context beyond them: dryRun writes nothing, the prior script is saved to version History for undo, confirmReplace is mandatory for replace, the title page is only kept on replace/empty script, and missing names are created as story elements returned in createdEntities.

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?

Front-loads formats and the dryRun-first instruction before the detail-heavy linking and insertPosition sections, which is good ordering. It is long for a tool description, and a few linking sentences repeat the same cue-extension rule, but almost every sentence carries operational weight given the destructive, multi-format import.

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?

Though there is no output schema, the description compensates by describing what dryRun returns (scene list, element counts, link targets with near-miss candidates) and what the real call returns (createdEntities). Combined with the safety, undo, and replace conditions, an agent has everything needed to call this 8-parameter destructive tool 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 100% so the baseline is 3, but the description adds real meaning the schema lacks: entityMap keys are the file's names with cue extensions ignored, only characters and places are mappable, and mapped cues take the entity name while keeping their extension. insertPosition and format semantics are largely already in the schema descriptions, so this stops short of a full 5.

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 (import) and resource (script), enumerates the accepted source formats (fdx, WriterDuet json, Fountain/plain text), and later explicitly carves itself away from edit_script. An agent can identify and differentiate this tool from siblings like edit_script and extract_file_text without opening the 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 an explicit workflow (dryRun:true first, then import with entityMap), names the alternative for PDFs/scans (extract_file_text, then import by textId), and states an explicit exclusion (non-screenplay text must go to edit_script). It also tells the agent to ask the user before replace, covering the risky path.

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