MCP / Tools

Tools

41 public tools, grouped into families. Every tool is a thin adapter over a BeatBandit backend capability — schema validated, auth scoped, credit accounted, and idempotency aware where it matters.

Core Project 3

Discover, create, and read BeatBandit projects and templates.

Tool	Kind	Stability	Description
`project_mutate`	write	beta	Create or update project-level metadata, settings, and defaults, returning compact stable project identity for follow-up MCP calls.
`project_query`	read	beta	List accessible projects, read one project by stable id, re-find a project by exact name, or inspect canonical Novel development, adaptation source, Chapter, manuscript, Voice, audit, canon, candidate, and export-readiness state.
`template_list`	read	beta	List available BeatBandit templates and return a compact project creation next-action template.

Story Graph 3

Read and mutate the story-graph primitives: cards, scenes, and the graph itself.

Tool	Kind	Stability	Description
`story_entity_propose`	orchestration	draft	Quote first, then accept Start with both billing IDs.
`story_entity_query`	read	beta	List, get, or search story graph entities such as cards, scenes, episodes, arcs, and relationships.
`story_mutate`	write	beta	Create agreed story cards or scenes, or make exact updates, reordering and deletions to story entities.

Screenplay 9

Read, propose, and apply changes to structured screenplay documents.

Tool	Kind	Stability	Description
`screenplay_draft_apply`	write	beta	Use after the user approves a complete scene or episode draft saved by screenplay_proposal_create.
`screenplay_edit_apply`	write	beta	Use to apply user-approved passage edits returned by screenplay_edit_propose, retaining their base_rev, targets and preimages.
`screenplay_edit_propose`	orchestration	beta	Quote, start accepted generation, and finalize revision-aware screenplay edits for a selected passage.
`screenplay_import_run`	orchestration	beta	Import screenplay scenes, beats and canonical pages.
`screenplay_proposal_create`	write	beta	Save supplied scene or whole-episode text as a reviewable draft.
`screenplay_proposal_query`	read	beta	List or read complete saved screenplay proposals, source evidence, and their native review or Apply authority.
`screenplay_read`	read	beta	Read compact screenplay document context, one episodic screenplay, one movie sequence, one scene, or the explicit full document from BeatBandit's structured screenplay editor.
`screenplay_rewrite_run`	orchestration	beta	Propose direction-driven screenplay rewrites scoped to scenes, ranges, characters or the whole draft.
`screenplay_snapshot_apply`	write	beta	Use when the user has exact text or block changes to save: replace, insert or delete text/blocks, update block metadata, or replace a scene from Fountain/plain text.

Story Workflows 10

Run backend-owned parent workflows for development, revision, review, and screenplay generation.

Tool	Kind	Stability	Description
`genre_contract`	write	beta	Apply the selected Genre Movie contract.
`genre_contract_query`	read	beta	Read, inspect the registry, or preview a Genre Movie contract without applying changes.
`screenplay_generation_run`	orchestration	beta	Use when an existing outline is ready for screenplay prose: a movie/TV draft, selected episodes, a scene, or dependent pages for a saved story revision.
`screenplay_writing_voice`	orchestration	beta	Save or select the project Writing Voice.
`screenplay_writing_voice_analyze`	orchestration	beta	Check readiness, quote, start, or finalize Writing Voice analysis.
`screenplay_writing_voice_query`	read	beta	Read the complete saved Writing Voice, a transparent preset, or completed analysis proposals.
`story_development_run`	orchestration	beta	Generate whole outlines, scene lists, sequences, treatments, trailers, episodes, weave plans, or original/adapted Novels.
`story_review_run`	orchestration	beta	REVIEW existing project material and produce editorial feedback — room review (writers'-room style holistic notes), analysis wizard (scored editorial pass with rewrite guidance and comps), or continuity audit / Sync Screenplay (generate, review, and explicitly apply screenplay rewrite suggestions for pending structural-sync update tasks), or Novel audits, reviewable shared manuscript proposals, revision-checked Canon Ledger updates, AI prose edits of a selected manuscript passage, and plan updates from written prose.
`story_revision_run`	orchestration	beta	Use when an existing story needs structural changes, connected planning/page revisions, dialogue polish, alternative directions, or planning-to-pages comparison.
`take_wizard_run`	orchestration	beta	Quote, then explicitly start 2-5 distinct premise TAKES from raw story material before any beats exist - Faithful, More Dramatic, Wildcard, Intimate, High Concept.

Story Collaboration 1

Collaborate with BeatBandit through conversational guidance and persona-driven passes.

Tool	Kind	Stability	Description
`agent_persona_run`	orchestration	beta	Run personas once to propose applyable changes to existing project material.

Shot / Media / Export 10

Generate shot lists, images, videos, and export artifacts.

Tool	Kind	Stability	Description
`asset_upload`	write	beta	Upload a local, public-URL, or base64 image/audio into BeatBandit as a shot image, recurring shot-element reference, scene moodboard asset, project visual-style reference, or reusable voice reference.
`export_create`	export	beta	Start exports and retrieve export artifacts.
`export_query`	read	beta	List owned project exports or reopen one retained export without regenerating it.
`image_generate`	orchestration	beta	Generate still-image assets, with distinct workflows for per-shot storyboard/frame images, reusable shot-element references, and scene-level moodboards; fal-backed requests return an async job to poll with `job_get`.
`media_generate`	orchestration	beta	Generate music, speech, dialogue, sound effects, or shot-scoped scene audio.
`shot_list_generate`	orchestration	beta	Run or cancel BeatBandit's backend-owned shot-list generation workflow for a project, scene, or episode scope.
`shot_list_query`	read	beta	Read shot-list scope summaries, shots, recurring elements, and linked shot assets.
`shot_mutate`	write	beta	Create, update, delete, reorder, or reposition shots, recurring shot elements, scene moodboard selections, selected shot-audio takes, and reviewed video-continuity checkpoints inside an existing shot-list scope using an entity_type discriminator.
`video_generate`	orchestration	beta	Generate shot videos and start video timeline exports, with discoverable model constraints, reference roles, prompt/default resolution, and asset handoff metadata.
`voice_profile`	write	beta	List, create, update, archive, and attach reusable voice reference samples for Seed Audio workflows.

Asset Query 2

Filter generated media and shot-element libraries without leaving the MCP surface.

Tool	Kind	Stability	Description
`asset_display`	read	beta	Display one BeatBandit asset with inline image rendering or media-ready metadata.
`project_assets_query`	read	beta	Filter generated media assets, recurring shot elements, or scene moodboards for one BeatBandit project.

Jobs 1

Poll async workflow progress through the canonical job surface.

Tool	Kind	Stability	Description
`job_get`	orchestration	beta	Observe an accepted async job and its results.

Other 2

Tool	Kind	Stability	Description
`account_mutate`	write	beta	Update caller-scoped account preferences such as the default BeatBandit LLM identifier and default video model path.
`novel_mutate`	write	beta	Make exact Novel Chapter structure, manuscript/private-note, metadata, checkpoint/restore or manual Writing Voice changes using native revision guards.