MCP / Tools / Story Workflows / screenplay_writing_voice

screenplay_writing_voice

orchestrationbetaauth: project:writeapproval: suggeststatus: v1

Save or select the project Writing Voice. Inspect with screenplay_writing_voice_query; analyze with screenplay_writing_voice_analyze.

When to use

Save or select the project Writing Voice. Inspect with screenplay_writing_voice_query; analyze with screenplay_writing_voice_analyze.

When not to use

Do not use for Novel Writing Voice; use `story_development_run(workflow=novel_adaptation)`.
Do not use for character or narrator audio references; use `voice_profile`.
Do not use for `tv_season`, which plans a season but does not write screenplay pages.
Analysis never saves. Saving Custom Voice explicitly activates its new revision.

Examples

“Use screenplay_writing_voice operation=save for project 123.”
“Use screenplay_writing_voice operation=select for project 123.”

Anti-examples

Clone a Novel Voice profile into a screenplay project.
Create a speech reference sample for a character.

Backend capabilities

screenplay_writing_voice.savescreenplay_writing_voice.select

Linked resources

Tool calls may return resource_links pointing at these resource families.

screenplay_writing_voice screenplay_writing_voice_proposal

Input schema

screenplay_writing_voice input

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": [
    "operation",
    "project_id"
  ],
  "properties": {
    "operation": {
      "type": "string",
      "enum": [
        "select",
        "save"
      ]
    },
    "project_id": {
      "type": "integer"
    },
    "expected_revision": {
      "type": "integer",
      "minimum": 0
    },
    "if_match_updated_at": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "selection": {
      "oneOf": [
        {
          "type": "object",
          "required": [
            "kind",
            "preset_id"
          ],
          "properties": {
            "kind": {
              "const": "preset"
            },
            "preset_id": {
              "type": "string",
              "minLength": 1,
              "maxLength": 80
            }
          },
          "additionalProperties": false
        },
        {
          "type": "object",
          "required": [
            "kind",
            "revision"
          ],
          "properties": {
            "kind": {
              "const": "custom"
            },
            "revision": {
              "type": "integer",
              "minimum": 1
            }
          },
          "additionalProperties": false
        }
      ]
    },
    "voice": {
      "type": "object",
      "required": [
        "schema_version",
        "label",
        "action_style",
        "dialogue_style",
        "page_rhythm"
      ],
      "properties": {
        "schema_version": {
          "const": 1
        },
        "label": {
          "type": "string",
          "minLength": 1,
          "maxLength": 120
        },
        "action_style": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4000
        },
        "dialogue_style": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4000
        },
        "page_rhythm": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4000
        },
        "tone_and_atmosphere": {
          "type": "string",
          "maxLength": 4000
        },
        "voice_boundaries": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1
          },
          "maxItems": 8,
          "uniqueItems": true
        },
        "samples": {
          "type": "array",
          "maxItems": 3,
          "items": {
            "type": "object",
            "required": [
              "sample_id",
              "label",
              "excerpt"
            ],
            "properties": {
              "sample_id": {
                "type": "string",
                "minLength": 1,
                "maxLength": 80
              },
              "label": {
                "type": "string",
                "minLength": 1,
                "maxLength": 120
              },
              "excerpt": {
                "type": "string",
                "minLength": 1,
                "maxLength": 30000
              }
            },
            "additionalProperties": false
          }
        }
      },
      "additionalProperties": false
    }
  },
  "allOf": [
    {
      "if": {
        "properties": {
          "operation": {
            "const": "select"
          }
        }
      },
      "then": {
        "required": [
          "selection"
        ]
      }
    },
    {
      "if": {
        "properties": {
          "operation": {
            "const": "save"
          }
        }
      },
      "then": {
        "required": [
          "expected_revision",
          "voice"
        ]
      }
    }
  ],
  "additionalProperties": false
}

Output schema

screenplay_writing_voice output

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": [
    "operation",
    "project_id",
    "writing_voice_updated_at"
  ],
  "properties": {
    "operation": {
      "type": "string",
      "enum": [
        "select",
        "save"
      ]
    },
    "project_id": {
      "type": "integer"
    },
    "mode": {
      "type": [
        "string",
        "null"
      ]
    },
    "revision": {
      "type": "integer",
      "minimum": 0
    },
    "writing_voice_updated_at": {
      "type": [
        "string",
        "null"
      ]
    },
    "exists": {
      "type": "boolean"
    },
    "label": {
      "type": [
        "string",
        "null"
      ]
    },
    "sample_count": {
      "type": "integer",
      "minimum": 0,
      "maximum": 3
    },
    "selection": {
      "type": "object",
      "additionalProperties": true
    },
    "preset_summaries": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": true
      }
    },
    "preset": {
      "type": "object",
      "additionalProperties": true
    },
    "async": {
      "type": "boolean"
    },
    "job_id": {
      "type": [
        "string",
        "null"
      ]
    },
    "status": {
      "type": [
        "string",
        "null"
      ]
    },
    "readiness": {
      "type": "object",
      "additionalProperties": true
    },
    "proposal_summaries": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": true
      }
    },
    "estimated_credits": {
      "type": "integer",
      "minimum": 0
    },
    "credits_charged": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 0
    },
    "billing_pending": {
      "type": "boolean"
    },
    "billing_status": {
      "type": "string"
    },
    "billing_operation_id": {
      "type": "string",
      "format": "uuid"
    },
    "quote": {
      "type": "object",
      "additionalProperties": true
    },
    "reserved_credits": {
      "type": "integer",
      "minimum": 0
    },
    "credits_skipped_reason": {
      "type": "string"
    },
    "resource_links": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": true
      }
    },
    "next_actions": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": true
      }
    }
  },
  "additionalProperties": true
}