story_entity_propose
Quote first, then accept Start with both billing IDs. Retry with the same IDs. 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
story.entity_propose
Input schema
story_entity_propose input
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": [
"project_id",
"entity_type",
"entity_id",
"phase"
],
"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`.",
"maxLength": 100,
"minLength": 1
},
"stage_id": {
"type": "string",
"description": "Optional. Strongly recommended when the same card can appear in multiple stages; controls stage-specific context and prompt selection.",
"maxLength": 200
},
"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.",
"maxLength": 200
},
"instruction": {
"type": "string",
"description": "Optional free-form guidance. Defaults to 'Provide strong alternatives that fit the story.'",
"maxLength": 4000
},
"writing_mode": {
"type": "string",
"description": "Optional. Mirrors the in-product chat writing_mode so stage-specific system prompts can be selected consistently.",
"maxLength": 100
},
"count": {
"type": "integer",
"minimum": 1,
"maximum": 5,
"description": "Number of proposed values to return. Defaults to 3."
},
"phase": {
"enum": [
"quote",
"start"
]
},
"billing_quote_id": {
"type": "string",
"format": "uuid"
},
"billing_request_id": {
"type": "string",
"format": "uuid"
}
},
"additionalProperties": false,
"allOf": [
{
"if": {
"properties": {
"phase": {
"const": "start"
}
}
},
"then": {
"required": [
"billing_quote_id",
"billing_request_id"
]
}
},
{
"if": {
"properties": {
"phase": {
"const": "quote"
}
}
},
"then": {
"not": {
"anyOf": [
{
"required": [
"billing_quote_id"
]
},
{
"required": [
"billing_request_id"
]
}
]
}
}
}
]
}Output schema
story_entity_propose output
{
"type": "object",
"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",
"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",
"null"
],
"minimum": 0
},
"phase": {
"enum": [
"quote",
"start"
]
},
"current_value": {},
"billing_operation_id": {
"type": "string",
"format": "uuid"
},
"billing_status": {
"type": "string"
},
"quote": {
"type": "object",
"required": [
"quote_id",
"mode",
"allowance",
"expires_at"
],
"properties": {
"quote_id": {
"type": "string",
"format": "uuid"
},
"mode": {
"enum": [
"fixed",
"usage"
]
},
"allowance": {
"type": "integer",
"minimum": 0
},
"expires_at": {
"type": "string"
}
},
"additionalProperties": true
}
},
"additionalProperties": false,
"required": [
"phase"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}← All toolsv1 · workflow_runner