screenplay_read
Read compact screenplay document context, one movie sequence, one scene, or the explicit full document from BeatBandit's structured screenplay editor.
When to use
Use compact `mode=document` for document metadata and scene/sequence links.
Use `mode=sequence` with `sequence_number` to read about one movie sequence at a time.
Use `mode=document` with `document_scope=full` only when the caller explicitly needs the entire screenplay payload.
Use `mode=scene` when the caller needs one focused screenplay scene.
When not to use
Do not use for story graph reads or screenplay mutation.
Do not treat an in-flight `screenplay_writer` parent job as already persisted; poll `job_get` first if screenplay generation is still active.
Examples
“Get a compact screenplay document summary for project 42.”
“Read sequence 3 from project 42.”
“Read scene 50.10.20 from project 42.”
Anti-examples
- Apply these screenplay edits immediately.
Backend capabilities
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": [
"mode",
"project_id"
],
"properties": {
"mode": {
"type": "string",
"enum": [
"document",
"scene",
"sequence"
]
},
"project_id": {
"type": "integer"
},
"document_scope": {
"type": "string",
"enum": [
"summary",
"full"
],
"description": "For mode=document, summary is the compact default. Use full only when the caller explicitly needs the entire screenplay payload."
},
"scene_id": {
"type": "string"
},
"sequence_number": {
"type": "integer",
"minimum": 1,
"maximum": 8,
"description": "For mode=sequence, read one movie sequence at a time."
}
},
"allOf": [
{
"if": {
"properties": {
"mode": {
"const": "scene"
}
}
},
"then": {
"required": [
"scene_id"
]
}
},
{
"if": {
"properties": {
"mode": {
"const": "sequence"
}
}
},
"then": {
"required": [
"sequence_number"
]
}
}
],
"additionalProperties": false
}Output schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": [
"mode"
],
"properties": {
"mode": {
"type": "string"
},
"document": {
"type": "object"
},
"document_scope": {
"type": "string"
},
"document_summary": {
"type": "object"
},
"sequence": {
"type": "object"
},
"scene": {
"type": "object"
},
"resource_links": {
"type": "array",
"items": {
"type": "object"
}
}
},
"additionalProperties": true
}