story_mutate
Create, update, reorder, or delete story-graph entities using an entity_type discriminator. Use this for deliberate low-level card, scene, and story-graph mutations once BeatBandit has already identified the exact entities you want to change.
When to use
Use when you already know the exact project id, entity_type, and entity fields you want to mutate.
Use `entity_type=card` with top-level `operation`, numeric `project_id`, `card_code`, and object `fields` for card-family CRUD.
Use `entity_type=scene` with top-level `operation`, numeric `project_id`, `scene_id`, and object `fields_patch` / `scene_data` for scene-family CRUD and ordering.
Use `entity_type=graph` for episodes, arcs, and relationships.
When not to use
Do not use for screenplay block edits; use `screenplay_edit_*` for natural-language edits or `screenplay_snapshot_apply` for direct snapshot block mutations.
Do not start here when the user only has a raw story idea; prefer `story_development_run`.
Do not use for image, visual reference, storyboard, moodboard, recurring-image, shot, shot-element, or media-asset work; use `project_assets_query` / `shot_list_query` for reads, `shot_mutate` for shot or recurring-element mutations, and `image_generate` for still-image generation.
Examples
“Update one protagonist card summary.”
“Update treatment card 50.10.10 with `entity_type=card`, `operation=update`, `project_id=1041`, `card_code=50.10.10`, and `fields={"Treatment - Act 1":"..."}`.”
“Reorder scenes inside an existing outline.”
“Link a scene to a storyline arc.”
Anti-examples
- Generate a brand-new scene outline from an idea.
- Rewrite selected screenplay dialogue.
- Update a card with `code` or `entity_id` instead of `card_code`; use the schema field names exactly.
- Create a recurring element for Anna or prepare character reference images; use `shot_mutate(entity_type=element)` and `image_generate(workflow=generate_element)`.
Workflows
Switch behavior by setting the entity_type input field.
card
Calls: story.card_mutatescene
Calls: story.scene_mutategraph
Calls: story.graph_mutateInput schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": [
"entity_type",
"operation",
"project_id"
],
"properties": {
"entity_type": {
"type": "string",
"enum": [
"card",
"scene",
"graph"
],
"description": "Choose which story graph family to mutate. This schema intentionally exposes all variant fields at top level so MCP clients do not need to resolve nested oneOf refs."
},
"operation": {
"type": "string",
"enum": [
"create",
"update",
"delete",
"update_fields",
"reorder",
"update_position",
"update_beats",
"relationship_upsert",
"relationship_delete",
"episode_create",
"episode_update",
"episode_delete",
"episode_reorder",
"storyline_arc_create",
"storyline_arc_update",
"storyline_arc_delete"
],
"description": "Operation for the selected entity_type. Card operations: create/update/delete. Scene operations: create/update_fields/delete/reorder/update_position/update_beats. Graph operations: relationship_*, episode_*, storyline_arc_*."
},
"project_id": {
"type": "integer",
"description": "Numeric BeatBandit project id. Pass as a JSON number, not a string."
},
"if_match_updated_at": {
"type": "string"
},
"card_code": {
"type": "string",
"description": "For entity_type=card, exact card code to update, for example 50.10.10. Use card_code, not code or entity_id."
},
"name": {
"type": "string"
},
"card_type": {
"type": "string"
},
"stage_id": {
"type": "string"
},
"fields": {
"type": "object",
"description": "For entity_type=card, object of card field updates. Pass as a JSON object, not a stringified JSON blob."
},
"position": {
"type": "integer"
},
"info": {
"type": "string"
},
"scene_id": {
"type": "string",
"description": "For entity_type=scene, exact scene card id/code to update."
},
"scene_data": {
"type": "object"
},
"after_scene_id": {
"type": "string"
},
"fields_patch": {
"type": "object",
"description": "For entity_type=scene, object of scene field updates. Pass as a JSON object, not a stringified JSON blob."
},
"scene_order": {
"type": "array",
"items": {
"type": "string"
}
},
"beat_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"source_card_code": {
"type": "string"
},
"target_card_code": {
"type": "string"
},
"relationship_type": {
"type": "string"
},
"strength": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"notes": {
"type": "string"
},
"episode_id": {
"type": "string"
},
"episode_name": {
"type": "string"
},
"episode_fields": {
"type": "object"
},
"episode_order": {
"type": "array",
"items": {
"type": "string"
}
},
"arc_code": {
"type": "string"
},
"arc_name": {
"type": "string"
},
"arc_fields": {
"type": "object"
}
},
"allOf": [
{
"if": {
"properties": {
"entity_type": {
"const": "card"
}
}
},
"then": {
"properties": {
"operation": {
"enum": [
"create",
"update",
"delete"
]
}
}
}
},
{
"if": {
"properties": {
"entity_type": {
"const": "scene"
}
}
},
"then": {
"properties": {
"operation": {
"enum": [
"create",
"update_fields",
"delete",
"reorder",
"update_position",
"update_beats"
]
}
}
}
},
{
"if": {
"properties": {
"entity_type": {
"const": "graph"
}
}
},
"then": {
"properties": {
"operation": {
"enum": [
"relationship_upsert",
"relationship_delete",
"episode_create",
"episode_update",
"episode_delete",
"episode_reorder",
"storyline_arc_create",
"storyline_arc_update",
"storyline_arc_delete"
]
}
}
}
}
],
"additionalProperties": false
}Output schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": [
"entity_type",
"result"
],
"properties": {
"entity_type": {
"type": "string",
"enum": [
"card",
"scene",
"graph"
]
},
"result": {
"type": "object"
}
},
"additionalProperties": true
}