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.