screenplay_rewrite_run
Propose direction-driven screenplay rewrites scoped to scenes, ranges, characters or the whole draft. Quote and obtain acceptance before Start; reuse billing IDs on retries.
When to use
- Readiness checks scope. Quote first, show the price, then Start with billing_quote_id and a fresh billing_request_id; reuse both on retries.
- For a passage use range_rewrite with scope.block_range scene_id/start_block_id/end_block_id from screenplay_read.
- Poll job_get, finalize by job_id, then apply canonical proposals by proposal_id. To keep only some changes, pass operation_ids (screenplay_ops op_ids; planning card:<code>:<field>/create:<code>); declined operations close with the proposal.
- Proposed sources include revision_id, source_selection and optional page_proposal_ids in readiness/quote/Start. Finalize identifies proposal_workflow and derived_page_proposal_ids. Review/decide through story_revision_run planning_revision or scene_list_revision, retaining selected operation_ids and page_proposal_ids. Never apply a structural parent here.
When not to use
- For story/page reconciliation use Sync Screenplay/project_updates, for narrow edits use screenplay_edit_*, and for exact scene or block replacement use screenplay_snapshot_apply (replace_scene_from_text for pasted scenes).
Examples
- “Sharpen a scene; rewrite a passage or one character's dialogue.”
Anti-examples
- Reading; exact pasted replacements; new outlines.
Backend capabilities
screenplay_rewrite.run
Linked resources
Tool calls may return resource_links pointing at these resource families.
Input schema
screenplay_rewrite_run input
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": [
"workflow",
"phase",
"project_id"
],
"properties": {
"workflow": {
"type": "string",
"enum": [
"scene_rewrite",
"range_rewrite",
"character_rewrite",
"whole_rewrite"
]
},
"phase": {
"type": "string",
"enum": [
"quote",
"readiness",
"start",
"finalize",
"apply"
]
},
"project_id": {
"type": "integer"
},
"direction": {
"type": "string",
"minLength": 1,
"maxLength": 8000
},
"scope": {
"type": "object",
"properties": {
"scene_id": {
"type": "string"
},
"scene_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"character_name": {
"type": "string"
},
"sequence_code": {
"type": "string"
},
"act_code": {
"type": "string"
},
"block_range": {
"type": "object",
"description": "Inclusive screenplay passage anchor for workflow=range_rewrite. Use block IDs returned by screenplay_read. Recommended shape: {\"scene_id\":\"...\",\"start_block_id\":\"...\",\"end_block_id\":\"...\"}; omit end_block_id for a single-block range.",
"properties": {
"scene_id": {
"type": "string",
"description": "Screenplay scene or episode ID containing the selected range."
},
"start_block_id": {
"type": "string",
"description": "Inclusive first screenplay block ID from screenplay_read."
},
"end_block_id": {
"type": "string",
"description": "Inclusive last screenplay block ID from screenplay_read. Omit when rewriting one block."
}
},
"additionalProperties": true
}
},
"additionalProperties": false
},
"proposal_id": {
"type": "string"
},
"job_id": {
"type": "string"
},
"operation_ids": {
"type": "array",
"minItems": 1,
"maxItems": 500,
"uniqueItems": true,
"description": "Apply only: selected operation IDs from the saved proposal. Screenplay edits use screenplay_ops.ops[].op_id; planning uses review change IDs card:<code>:<field> and create:<code>. Omit to apply everything. The proposal then closes and its receipt lists applied and declined IDs.",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 200
}
},
"revision_id": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"source_selection": {
"type": "object",
"additionalProperties": false,
"required": [
"proposal_id",
"operation_ids"
],
"properties": {
"proposal_id": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"operation_ids": {
"type": "array",
"maxItems": 500,
"uniqueItems": true,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 120
}
},
"edited_fields": {
"type": "object",
"maxProperties": 500,
"additionalProperties": {
"type": "object",
"additionalProperties": true
}
}
}
},
"page_proposal_ids": {
"type": "array",
"maxItems": 20,
"uniqueItems": true,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 200
}
},
"billing_quote_id": {
"type": "string",
"format": "uuid"
},
"billing_request_id": {
"type": "string",
"format": "uuid"
}
},
"additionalProperties": false,
"allOf": [
{
"if": {
"properties": {
"phase": {
"enum": [
"quote",
"start"
]
}
}
},
"then": {
"required": [
"direction"
]
}
},
{
"if": {
"properties": {
"phase": {
"const": "finalize"
}
}
},
"then": {
"required": [
"job_id"
]
}
},
{
"if": {
"properties": {
"phase": {
"const": "apply"
}
}
},
"then": {
"required": [
"proposal_id"
]
}
},
{
"if": {
"required": [
"source_selection"
]
},
"then": {
"required": [
"revision_id"
],
"properties": {
"phase": {
"enum": [
"readiness",
"start",
"quote"
]
}
}
}
},
{
"if": {
"required": [
"revision_id"
]
},
"then": {
"required": [
"source_selection"
]
}
},
{
"if": {
"required": [
"page_proposal_ids"
],
"properties": {
"page_proposal_ids": {
"minItems": 1
}
}
},
"then": {
"required": [
"source_selection"
]
}
},
{
"if": {
"properties": {
"phase": {
"const": "start"
}
}
},
"then": {
"required": [
"billing_quote_id",
"billing_request_id"
]
},
"else": {
"not": {
"anyOf": [
{
"required": [
"billing_quote_id"
]
},
{
"required": [
"billing_request_id"
]
}
]
}
}
},
{
"if": {
"required": [
"operation_ids"
]
},
"then": {
"properties": {
"phase": {
"const": "apply"
}
}
}
}
]
}Output schema
screenplay_rewrite_run output
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": [
"phase",
"workflow"
],
"properties": {
"phase": {
"type": "string"
},
"workflow": {
"type": "string"
},
"proposal_id": {
"type": "string"
},
"summary": {
"type": "array",
"items": {
"type": "object"
}
},
"updates": {
"type": "array",
"items": {
"type": "object"
}
},
"creates": {
"type": "array",
"items": {
"type": "object"
}
},
"notes_patch": {
"type": "object"
},
"screenplay_ops": {
"type": "object"
},
"readiness": {
"type": "object"
},
"applied_summary": {
"type": "object"
},
"snapshot_rev": {
"type": "integer"
},
"credits_charged": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"credits_skipped_reason": {
"type": "string"
},
"no_op_reason": {
"type": "string"
},
"resource_links": {
"type": "array",
"items": {
"type": "object"
}
},
"quote": {
"type": "object",
"required": [
"quote_id",
"mode",
"allowance",
"expires_at"
],
"properties": {
"quote_id": {
"type": "string",
"format": "uuid"
},
"mode": {
"enum": [
"fixed",
"usage"
]
},
"allowance": {
"type": "integer",
"minimum": 0
},
"expires_at": {
"type": "string"
}
},
"additionalProperties": true
},
"billing_operation_id": {
"type": "string",
"format": "uuid"
},
"billing_status": {
"type": "string"
}
},
"additionalProperties": true
}← All toolsv1 · workflow_runner