screenplay_generation_run
WRITE actual screenplay prose from existing structured story material. The verb is WRITE: turn already-built beats, scenes, or episodes into formatted screenplay text. `screenplay_writer` is chunk-scoped for feature movies and multi-act scene-oriented TV templates such as `tv_60`: call readiness first, then start one resolved chunk with `payload.granularity` and 1-based `payload.chunk_index`, then poll `job_get` until completion. Prefer `granularity="full"` with `chunk_index=1` when readiness/model capability allows it; it is the fastest and cheapest complete-screenplay path. Legacy `payload.sequence_number` remains accepted for focused one-sequence/act generation. If chunk fields are omitted, the backend uses the project's remembered scope, or Full when no remembered scope exists and the selected model/template allows it, otherwise Sequence. Short-movie and one-scene projects may omit chunk fields (BeatBandit uses section 1). `episode_screenplay` is a backend-owned episode-list parent workflow for templates such as `single_scene` and `micro_drama`; start accepts 1-10 `payload.episode_ids` per call, with optional `payload.episodes_per_call` (default 10, max 10) to choose a smaller batch-size cap for that call. Split larger episode lists into batches. Use `scene_screenplay` for first-draft prose on one explicit scene or one small explicit scene batch only. `scene_screenplay` also supports `payload.generate_proposal=true` for Scene List Revision merge survivors: it produces a reviewable `diff_proposal` before mutating prose, so the caller can approve/apply survivor rewrites before Sync Screenplay ripple checks. It is not a substitute for the full feature pipeline (`treatment_wizard` → `sequence_wizard` → `screenplay_writer`). The structured outline must already exist; this tool does not build it.
When to use
The structured outline already exists and you want actual screenplay prose — the verb is WRITE.
Use `screenplay_writer` for movie or `tv_60` prose with `payload.granularity="full"` and `payload.chunk_index=1` when the selected model supports that scope.
Use smaller `screenplay_writer` chunks (`sequence`, movie `act`, or `half`) for focused reruns or when the selected model cannot support `full`.
Use `screenplay_writer` without `payload.sequence_number` for short-movie or one-scene projects; they default to section 1.
Use `episode_screenplay` for episode-list project prose generation across up to `payload.episodes_per_call` selected episodes per call (default 10, max 10).
Use `scene_screenplay` for first-draft prose on one scene or a small batch of up to 3 `payload.scene_codes`.
Use `scene_screenplay` with `payload.generate_proposal=true` and `payload.authoring_context` when `story_review_run(continuity_audit readiness)` reports `scene_authoring_required` after a Scene List Revision merge.
When not to use
Do not use for precise screenplay edits.
Do not manually switch to `screenplay_edit_*` or `screenplay_snapshot_apply` while an active screenplay generation parent job is still running.
Do not use to **build** the underlying structured outline (cards, beats, scenes) — use `story_development_run` (story_bootstrap, beat_wizard, scene_wizard) first.
Do not use `scene_screenplay` to bypass missing treatment or sequence guidance for a feature screenplay; complete `treatment_wizard` and `sequence_wizard`, then use `screenplay_writer`.
Do not use to **change or polish** the story structure — use `story_revision_run` (change_wizard, polish_wizard, creative_canvas) instead.
Do not use to **read** the existing screenplay or one scene — use `screenplay_read` or the `screenplay_document` / `screenplay_scene` resources.
Do not run continuity audit before applying required scene-authoring proposals for merge survivors; author the survivor prose first, then run `story_review_run(workflow=continuity_audit)`.
Examples
“Generate the full screenplay draft from this project with `screenplay_writer` full scope.”
“Regenerate sequence 1 of a screenplay draft from this project.”
“Generate a batch of up to 10 episodic screenplays for selected episodes.”
“Boundary - "Turn this finished outline into a full screenplay." Use `screenplay_writer` here because the structured outline already exists; we want prose now.”
“Boundary - "Write screenplay prose for one new scene I just outlined." Use `scene_screenplay` here.”
“Boundary - "Scene List Revision merged scenes and tells me survivor authoring is required." Use `scene_screenplay` with `payload.generate_proposal=true`, review the returned `diff_proposal`, then apply it.”
Anti-examples
- Read one screenplay scene.
- Outlining the story before any cards exist — that is `story_development_run` with `story_bootstrap`.
- Writing all scenes one-by-one with `scene_screenplay` because `screenplay_writer` readiness says treatment/sequence guidance is missing — finish those development stages instead.
- Sending more than 3 `scene_codes` in one `scene_screenplay` call — split into multiple focused batches.
- Sending more than `payload.episodes_per_call` episode IDs in one `episode_screenplay` call — split into batches.
- Polishing existing dialogue in a scene — that is `story_revision_run` with `polish_wizard`.
- Making a single surgical edit to existing screenplay prose — that is `screenplay_edit_propose` then `screenplay_edit_apply`.
Workflows
Switch behavior by setting the workflow input field.
screenplay_writer
episode_screenplay
scene_screenplay
Linked resources
Tool calls may return resource_links pointing at these resource families.
Input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": [
"workflow",
"phase",
"project_id"
],
"properties": {
"workflow": {
"type": "string",
"enum": [
"screenplay_writer",
"episode_screenplay",
"scene_screenplay"
]
},
"phase": {
"type": "string",
"enum": [
"readiness",
"start"
]
},
"project_id": {
"type": "integer"
},
"job_id": {
"type": "string"
},
"payload": {
"type": "object"
}
},
"allOf": [
{
"if": {
"properties": {
"workflow": {
"const": "screenplay_writer"
}
}
},
"then": {
"properties": {
"phase": {
"enum": [
"readiness",
"start"
]
},
"payload": {
"type": "object",
"properties": {
"sequence_number": {
"type": "integer",
"minimum": 1,
"maximum": 8,
"description": "Legacy alias for screenplay_writer start: equivalent to granularity=sequence with chunk_index equal to this sequence/act number. New callers should use granularity plus chunk_index."
},
"granularity": {
"type": "string",
"enum": [
"sequence",
"act",
"half",
"full"
],
"description": "For screenplay_writer start only: scope size for the writer call. Prefer full for a complete screenplay when the selected model supports it. If omitted, the backend uses the remembered project scope, or full when no remembered scope exists and full is allowed. sequence writes one sequence/act, act writes two movie sequences, half writes roughly half the screenplay, and full writes the whole screenplay."
},
"chunk_index": {
"type": "integer",
"minimum": 1,
"description": "For screenplay_writer start only: 1-based chunk position within the selected granularity. Use chunk_index=1 for full scope; movie half has chunk_index 1 for sequences 1-4 and 2 for sequences 5-8."
},
"template_id": {
"type": "string"
},
"regenerate": {
"type": "boolean"
},
"custom_guidance": {
"type": "string"
},
"llm_identifier": {
"type": "string",
"minLength": 1,
"description": "Optional provider/model override for this screenplay generation run. Uses the caller's saved default when omitted."
},
"options": {
"type": "object"
}
},
"additionalProperties": false
}
}
}
},
{
"if": {
"properties": {
"workflow": {
"const": "episode_screenplay"
}
}
},
"then": {
"properties": {
"phase": {
"enum": [
"readiness",
"start"
]
},
"payload": {
"type": "object",
"properties": {
"episode_ids": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"maxItems": 10,
"description": "For episode_screenplay start only: write a batch of 1-10 episode IDs. Use multiple episode_screenplay calls for larger episode lists."
},
"episodes_per_call": {
"type": "integer",
"minimum": 1,
"maximum": 10,
"description": "For episode_screenplay start only: optional batch-size cap for this call. Defaults to 10 and may not exceed 10."
},
"custom_guidance": {
"type": "string"
},
"llm_identifier": {
"type": "string",
"minLength": 1,
"description": "Optional provider/model override for this screenplay generation run. Uses the caller's saved default when omitted."
},
"target_duration_seconds": {
"type": "integer"
}
},
"additionalProperties": false
}
}
}
},
{
"if": {
"properties": {
"workflow": {
"const": "episode_screenplay"
},
"phase": {
"const": "start"
}
}
},
"then": {
"properties": {
"payload": {
"required": [
"episode_ids"
]
}
}
}
},
{
"if": {
"properties": {
"workflow": {
"const": "scene_screenplay"
}
}
},
"then": {
"properties": {
"phase": {
"enum": [
"readiness",
"start"
]
},
"payload": {
"type": "object",
"properties": {
"scene_id": {
"type": "string"
},
"scene_codes": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 3,
"description": "For scene_screenplay only: write a small explicit batch of 1-3 scene codes. Use multiple scene_screenplay calls for larger batches."
},
"custom_guidance": {
"type": "string"
},
"template_id": {
"type": "string"
},
"llm_identifier": {
"type": "string",
"minLength": 1,
"description": "Optional provider/model override for this screenplay generation run. Uses the caller's saved default when omitted."
},
"generate_proposal": {
"type": "boolean",
"description": "For scene_screenplay start only: generate a reviewable diff_proposal instead of immediately applying prose to the screenplay. Use this for Scene List Revision merge survivors."
},
"authoring_context": {
"type": "object",
"description": "For scene_screenplay proposal mode: captured survivor/absorbed prose plus the updated scene target from Scene List Revision."
}
},
"additionalProperties": false
}
}
}
},
{
"if": {
"properties": {
"workflow": {
"const": "scene_screenplay"
},
"phase": {
"enum": [
"readiness",
"start"
]
}
}
},
"then": {
"required": [
"payload"
],
"properties": {
"payload": {
"allOf": [
{
"oneOf": [
{
"required": [
"scene_id"
]
},
{
"required": [
"scene_codes"
]
}
]
},
{
"not": {
"required": [
"regenerate"
]
}
}
]
}
}
}
}
],
"additionalProperties": false
}Output schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": [
"workflow",
"phase"
],
"properties": {
"workflow": {
"type": "string"
},
"phase": {
"type": "string"
},
"async": {
"type": "boolean"
},
"job_id": {
"type": "string"
},
"readiness": {
"type": "object"
},
"result": {
"type": "object"
},
"recommended_action": {
"type": "string"
},
"screenplay_stage": {
"type": "string"
},
"project_id": {
"type": "integer"
},
"project_name": {
"type": "string"
},
"project_mode": {
"type": "string"
},
"proposal_id": {
"type": "string",
"description": "Saved diff proposal id when scene_screenplay runs in payload.generate_proposal mode."
},
"scene_authoring_segments": {
"type": "array",
"description": "Generated scene segments stored for review before explicit proposal apply.",
"items": {
"type": "object"
}
},
"base_screenplay_rev": {
"type": "integer",
"description": "Screenplay snapshot revision captured when the reviewable proposal was generated."
},
"sequence_number": {
"type": "integer"
},
"total_sequences": {
"type": [
"integer",
"null"
]
},
"valid_sequence_numbers": {
"type": "array",
"items": {
"type": "integer"
}
},
"structure_key": {
"type": [
"string",
"null"
]
},
"template_id": {
"type": "string"
},
"template_name": {
"type": "string"
},
"target_card_code": {
"type": "string"
},
"resource_links": {
"type": "array",
"items": {
"type": "object"
}
},
"pipeline_state": {
"$ref": "./_common/pipeline_state.schema.json"
},
"next_actions": {
"type": "array",
"items": {
"$ref": "./_common/next_action.schema.json"
}
}
},
"additionalProperties": true
}