story_entity_propose
Generate proposed values for a supported story entity field using BeatBandit's story context, craft rules, and writing-mode awareness. Non-mutating; apply is a separate mutate call. The current live entity types are `card` and `scene` (scene support is limited to free-text scene fields).
When to use
Use when the caller wants BeatBandit-authored field-level suggestions informed by the full story context instead of generating them locally without the template and context awareness.
Use after `story_entity_query` when the caller does not already have the exact target entity id and field name from recent tool output.
Use for both empty and filled fields on supported entities; the current value (if any) is included as seed context.
When not to use
Do not use for whole-stage regeneration — use the matching wizard (`beat_wizard.run`, `scene_wizard.run`, `treatment_wizard.run`, etc.).
Do not use as a read-only fetch — use `story_entity_query` or `project_query`.
Do not guess `field_name` values. If the field was not returned by `story_entity_query`, omit `field_name` and let BeatBandit resolve the entity's primary proposable field.
Examples
“Generate three loglines that lean into a specific theme.”
“Propose alternative motivations for a character card.”
“Propose alternative scene summaries or climaxes for an existing scene card.”
“Fill in an empty "Unique Element" field with options grounded in the protagonist and antagonist cards.”
Anti-examples
- Do not route UI navigation ("open the creative canvas") through this capability.
- Do not route whole-screenplay rewrites through this capability.
Backend capabilities
Input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": [
"project_id",
"entity_type",
"entity_id"
],
"properties": {
"project_id": {
"type": "integer",
"description": "BeatBandit project id."
},
"entity_type": {
"type": "string",
"enum": [
"card",
"scene"
],
"description": "Supported entity family to propose against. Current live values: `card`, `scene`."
},
"entity_id": {
"type": "string",
"description": "Stable entity identifier within the selected family. For `card`, this is the dotted card code (for example `10.10.10`). For `scene`, this is the scene card code / MCP `scene_id`."
},
"stage_id": {
"type": "string",
"description": "Optional. Strongly recommended when the same card can appear in multiple stages; controls stage-specific context and prompt selection."
},
"field_name": {
"type": "string",
"description": "Optional. Defaults to the entity's primary writable field. Provide only when it exactly matches a field returned by story_entity_query for this entity; otherwise omit it."
},
"instruction": {
"type": "string",
"description": "Optional free-form guidance. Defaults to 'Provide strong alternatives that fit the story.'"
},
"writing_mode": {
"type": "string",
"description": "Optional. Mirrors the in-product chat writing_mode so stage-specific system prompts can be selected consistently."
},
"count": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"description": "Number of proposed values to return. Defaults to 3."
}
},
"additionalProperties": false
}Output schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": [
"schema_version",
"project_id",
"entity_type",
"entity_id",
"field_name",
"entity_updated_at",
"suggestions",
"credits_charged"
],
"properties": {
"schema_version": {
"const": "story.entity_propose/v1"
},
"project_id": {
"type": "integer"
},
"project_name": {
"type": "string"
},
"entity_type": {
"type": "string",
"enum": [
"card",
"scene"
]
},
"entity_id": {
"type": "string"
},
"field_name": {
"type": "string"
},
"entity_updated_at": {
"type": "string",
"format": "date-time",
"description": "Echo back as `if_match_updated_at` when calling the matching mutate tool to avoid clobbering concurrent edits."
},
"suggestions": {
"type": "array",
"minItems": 1,
"maxItems": 5,
"items": {
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "string"
},
"reason": {
"type": [
"string",
"null"
]
},
"confidence": {
"type": [
"number",
"null"
],
"minimum": 0,
"maximum": 1
}
},
"additionalProperties": false
}
},
"context_summary": {
"type": "object",
"properties": {
"cards_used": {
"type": "array",
"items": {
"type": "string"
}
},
"tokens": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": false
},
"credits_charged": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": false
}