story_review_run
REVIEW existing project material and produce editorial feedback — room review (writers'-room style holistic notes), analysis wizard (scored editorial pass with rewrite guidance and comps), or continuity audit / Sync Screenplay (generate, review, and explicitly apply screenplay rewrite suggestions for pending structural-sync update tasks), or Novel audits, change proposals, and revision-checked Canon Ledger updates. For `continuity_audit`, `status` is the review surface and `apply` (or legacy `finalize`) is the selected mutating phase.
When to use
You want analytical feedback first, before deciding whether to mutate — the verb is REVIEW.
Use `room_review` for showrunner-style holistic notes across the project.
Use `analysis_wizard` for a scored editorial pass with rewrite guidance and comps.
Use `continuity_audit` as the MCP Sync Screenplay workflow after structural updates; call `phase=readiness`, then `phase=start`, poll with `job_get`, inspect `phase=status`, choose from the returned apply candidates, and commit explicit selections or acknowledgements with `phase=apply`.
If `continuity_audit` readiness returns `scene_authoring_required`, generate and apply the survivor prose proposal with `screenplay_generation_run(workflow=scene_screenplay, phase=start, payload.generate_proposal=true)` before starting continuity ripple checks.
Use `workflow=novel_review` with `payload.novel_operation=audit`, `change_proposal`, or `canon_entry`; audit findings never mutate content until an explicit proposal apply. After Audit completion, query `project_query(mode=novel, novel_mode=changes)`, inspect the full changes resource, then choose its revision-current apply or reject call.
When not to use
Do not use for direct low-level screenplay mutation; use `screenplay_snapshot_apply` for exact block edits.
Do not use to **change or polish** the story material — use `story_revision_run` (change_wizard, polish_wizard, creative_canvas) instead.
Do not use to **build** new structured material that does not exist yet — use `story_development_run` (scene_wizard, beat_wizard, story_bootstrap) instead.
Do not use `continuity_audit` for freeform scoped prose rewrites that are unrelated to pending structural-sync updates — use `screenplay_rewrite_run` instead.
Do not use Novel review operations as a raw manuscript overwrite path.
Examples
“Review this project like a showrunner.”
“Run Sync Screenplay readiness, start without copying update_ids, inspect status, choose suggestions, then apply explicit selections.”
“Boundary - "Get a scored editorial pass on this project with rewrite guidance." Use `analysis_wizard` here because the caller wants notes and scores, not committed changes.”
“Boundary - "Sync screenplay after I merged scenes." First author any merge survivor returned as `scene_authoring_required`, then use `continuity_audit` for ripple checks.”
“Run a full Novel audit with `workflow=novel_review`, `phase=readiness`, and `payload={"novel_operation":"audit","audit_level":"full"}`.”
Anti-examples
- Generate a new screenplay from scratch.
- Polishing dialogue in an existing scene — that is `story_revision_run` with `polish_wizard`.
- Generating new beats or scenes from an idea — that is `story_development_run` with `beat_wizard` or `scene_wizard`.
- Restructuring the story based on a free-form direction — that is `story_revision_run` with `change_wizard`.
Workflows
Switch behavior by setting the workflow input field.
room_review
analysis_wizard
continuity_audit
novel_review
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": [
"room_review",
"analysis_wizard",
"continuity_audit",
"novel_review"
]
},
"phase": {
"type": "string",
"enum": [
"readiness",
"start",
"status",
"finalize",
"apply",
"reject",
"update"
]
},
"project_id": {
"type": "integer"
},
"job_id": {
"type": "string"
},
"reservation_id": {
"type": "string"
},
"payload": {
"type": "object",
"properties": {
"model_hint": {
"type": "string",
"description": "Optional model hint for LLM-backed review generation."
},
"update_ids": {
"type": "array",
"description": "Explicit pending update ids for continuity_audit start. If omitted, start uses readiness' recommended structural-sync scene update ids.",
"items": {
"type": "string"
}
},
"include_global_updates": {
"type": "boolean",
"description": "For continuity_audit only: opt in to including global dirty markers alongside recommended structural-sync scene updates. Defaults to false."
},
"structural_card_codes": {
"type": "array",
"description": "Optional structural card code filter forwarded to continuity audit generation.",
"items": {
"type": "string"
}
},
"base_rev": {
"type": "integer",
"description": "Screenplay snapshot revision used when applying selected continuity suggestions. Not required for acknowledgement-only continuity_audit apply calls."
},
"selections": {
"type": "array",
"description": "Continuity suggestions to apply. Omit or pass [] only when acknowledged_dirty_scene_ids is non-empty.",
"items": {
"type": "object",
"required": [
"suggestion_id"
],
"properties": {
"suggestion_id": {
"type": "string"
},
"edited_after_text": {
"type": "string"
}
},
"additionalProperties": false
}
},
"acknowledged_dirty_scene_ids": {
"type": "array",
"description": "Dirty scene ids to acknowledge as aligned/no-change during continuity_audit apply.",
"items": {
"type": "string"
}
},
"acknowledged_update_ids": {
"type": "array",
"description": "Explicit pending update ids to acknowledge during continuity_audit apply. Use this for opt-in global dirty markers.",
"items": {
"type": "string"
}
},
"novel_operation": {
"type": "string",
"enum": [
"audit",
"change_proposal",
"canon_entry"
]
},
"audit_level": {
"type": "string",
"enum": [
"blueprint",
"chapter",
"full"
]
},
"chapter_card_id": {
"type": "integer",
"minimum": 1
},
"proposal_id": {
"type": "string",
"format": "uuid"
},
"entry_id": {
"type": "string",
"minLength": 1
},
"expected_revision": {
"type": "integer",
"minimum": 0
},
"entry": {
"type": "object"
}
},
"additionalProperties": false
}
},
"allOf": [
{
"if": {
"properties": {
"workflow": {
"const": "room_review"
}
}
},
"then": {
"properties": {
"phase": {
"enum": [
"readiness",
"start",
"finalize"
]
}
}
}
},
{
"if": {
"properties": {
"workflow": {
"const": "analysis_wizard"
}
}
},
"then": {
"properties": {
"phase": {
"enum": [
"readiness",
"start",
"finalize"
]
}
}
}
},
{
"if": {
"properties": {
"workflow": {
"const": "continuity_audit"
}
}
},
"then": {
"properties": {
"phase": {
"enum": [
"readiness",
"start",
"status",
"apply",
"finalize"
]
}
}
}
},
{
"if": {
"properties": {
"phase": {
"const": "finalize"
},
"workflow": {
"enum": [
"room_review",
"analysis_wizard"
]
}
}
},
"then": {
"required": [
"job_id"
]
}
},
{
"if": {
"properties": {
"workflow": {
"const": "continuity_audit"
},
"phase": {
"const": "readiness"
}
}
},
"then": {
"properties": {
"payload": {
"properties": {
"structural_card_codes": {
"description": "Optional filter for continuity audit readiness/start; readiness returns the pending update_ids to use."
}
}
}
}
}
},
{
"if": {
"properties": {
"workflow": {
"const": "continuity_audit"
},
"phase": {
"const": "start"
}
}
},
"then": {}
},
{
"if": {
"properties": {
"workflow": {
"const": "continuity_audit"
},
"phase": {
"enum": [
"apply",
"finalize"
]
}
}
},
"then": {
"required": [
"job_id",
"payload"
],
"properties": {
"payload": {
"anyOf": [
{
"required": [
"base_rev",
"selections"
],
"properties": {
"selections": {
"minItems": 1
}
}
},
{
"required": [
"acknowledged_dirty_scene_ids"
],
"properties": {
"acknowledged_dirty_scene_ids": {
"minItems": 1
}
}
},
{
"required": [
"acknowledged_update_ids"
],
"properties": {
"acknowledged_update_ids": {
"minItems": 1
}
}
}
]
}
}
}
},
{
"if": {
"properties": {
"workflow": {
"const": "novel_review"
}
},
"required": [
"workflow"
]
},
"then": {
"required": [
"payload"
],
"properties": {
"phase": {
"enum": [
"readiness",
"start",
"finalize",
"apply",
"reject",
"update"
]
},
"payload": {
"required": [
"novel_operation"
]
}
}
}
},
{
"if": {
"properties": {
"workflow": {
"const": "novel_review"
},
"phase": {
"enum": [
"readiness",
"start"
]
},
"payload": {
"properties": {
"novel_operation": {
"const": "audit"
}
},
"required": [
"novel_operation"
]
}
},
"required": [
"workflow",
"phase",
"payload"
]
},
"then": {
"properties": {
"payload": {
"required": [
"audit_level"
]
}
}
}
},
{
"if": {
"properties": {
"workflow": {
"const": "novel_review"
},
"phase": {
"const": "finalize"
},
"payload": {
"properties": {
"novel_operation": {
"const": "audit"
}
},
"required": [
"novel_operation"
]
}
},
"required": [
"workflow",
"phase",
"payload"
]
},
"then": {
"required": [
"job_id"
]
}
},
{
"if": {
"properties": {
"workflow": {
"const": "novel_review"
},
"payload": {
"properties": {
"novel_operation": {
"const": "change_proposal"
}
},
"required": [
"novel_operation"
]
}
},
"required": [
"workflow",
"payload"
]
},
"then": {
"properties": {
"phase": {
"enum": [
"apply",
"reject"
]
},
"payload": {
"required": [
"proposal_id"
]
}
}
}
},
{
"if": {
"properties": {
"workflow": {
"const": "novel_review"
},
"payload": {
"properties": {
"novel_operation": {
"const": "canon_entry"
}
},
"required": [
"novel_operation"
]
}
},
"required": [
"workflow",
"payload"
]
},
"then": {
"properties": {
"phase": {
"const": "update"
},
"payload": {
"required": [
"entry_id",
"expected_revision",
"entry"
]
}
}
}
}
],
"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"
},
"reservation_id": {
"type": "string"
},
"status": {
"type": "string"
},
"estimated_credits": {
"type": [
"integer",
"number"
]
},
"readiness": {
"type": "object"
},
"update_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"scene_authoring_required": {
"type": "array",
"description": "Scene ids that must be authored via screenplay_generation_run(scene_screenplay, payload.generate_proposal=true) before continuity_audit should run ripple checks.",
"items": {
"type": [
"string",
"object"
]
}
},
"defaulted_update_ids": {
"type": "boolean"
},
"suggestion_count": {
"type": "integer"
},
"dirty_result_count": {
"type": "integer"
},
"changed_scene_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"no_change_scene_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"conflict_count": {
"type": "integer"
},
"recommended_apply_args": {
"type": [
"object",
"null"
]
},
"apply_candidates": {
"type": "array",
"items": {
"type": "object"
}
},
"acknowledgement_candidates": {
"type": "object"
},
"result": {
"type": "object"
},
"summary": {
"type": "string"
},
"notes": {
"type": "array",
"items": {
"type": "object"
}
},
"note_count": {
"type": [
"integer",
"number"
]
},
"top_note_titles": {
"type": "array",
"items": {
"type": "string"
}
},
"suggested_capability_ids": {
"type": "array",
"items": {
"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"
}
},
"credits_charged": {
"type": "number",
"minimum": 0
},
"credits_previously_committed": {
"type": "number",
"minimum": 0
},
"credit_status": {
"type": "string",
"enum": [
"quoted",
"reserved",
"committed",
"refunded",
"not_metered",
"unavailable"
]
},
"credits_quoted": {
"type": "number",
"minimum": 0
},
"credits_reserved": {
"type": "number",
"minimum": 0
},
"credits_refunded": {
"type": "number",
"minimum": 0
},
"credits_skipped_reason": {
"type": "string"
}
},
"additionalProperties": true
}