agents

MCP tool reference

Every tool the Cadenza MCP server exposes: parameters, cost behavior, and when an agent should reach for each.

Last updated 2026-07-10

Thirteen tools, one engine. Every tool is a thin mapping onto the same REST endpoints the studio uses (API reference); nothing here is a downgraded agent tier. Free planning tools spend nothing; generation tools are billable; publishing requires explicit per-platform confirmation.

Tool	Cost	What it does
`get_story_intelligence_report`	free	Advisory story notes + shot plan, no render
`plan_director_prompt`	free	Full direction plan + per-model prompt dialects
`list_models`	free	Model roster with capabilities and cost tiers
`list_brand_profiles` / `set_brand_profile`	free	Brand Memory read/write
`generate_video`	billable	Directed multi-shot sequence, text to video
`generate_video_staged`	billable	LOOK LOCK: inspectable hero frame, then video
`animate_image`	billable	Animate your own image, continuity-locked
`ad_from_url`	billable	Product URL to on-brand ad
`refine_shot`	billable	Regenerate one shot, others stay locked
`extend_sequence`	billable	Add shots that inherit the locked look
`list_publish_connections`	free	Connected publish platforms
`publish_video`	free to preview	Preview drafts, then post only confirmed platforms

Planning tools (free, call these first)

get_story_intelligence_report

The reasoning layer standalone: advisory Story Intelligence notes plus the proposed shot plan for an intent, without generating. Build a pre-flight or storyboard UI on it, or let the agent sanity-check an idea before any spend.

Parameter	Type	Notes
`raw_intent`	string, required	What to evaluate, however rough
`director_mode`	string	Mode id or `auto`
`shot_count`	number	3 to 5

plan_director_prompt

The full Cinematic Research Engine plan: cinematic idiom and classic shot progression, edit timeline with beat timecodes, physics-checked camera plan per shot (lens, field of view, depth of field, motion blur), frame-rate and shutter feel, depth and occlusion layers, color grade, a weighted 0 to 10 artifact-risk score with suggested simplifications, and the same plan translated into each model's native prompt dialect. Iterate here, then generate.

Parameter	Type	Notes
`raw_intent`	string, required	The idea to direct
`target_model`	string	Which dialect `final_prompt` uses (default seedance_2_0)
`duration_seconds`	number
`shot_count`	number	3 to 5, default 5
`director_mode`	string	Mode id or `auto`

list_models

The routable model roster: per-model status, capabilities (duration ceiling, resolution, audio, camera control, physics), cost tier, and what each model is best for. Use it to reason about model_override before generating. Requires only the read scope, which also makes it the standard connection test.

Generation tools (billable)

Note: Safety-blocked requests spend nothing. Every returned asset carries provenance. Real-person likeness requires the likeness_consent attestation and is default-deny.

generate_video

Rough intent in, directed sequence out: shot plan, per-shot render, provenance. The full engine, story reasoning and no-drift continuity included.

Parameter	Type	Notes
`raw_intent`	string, required	e.g. 'premium running-shoe brand film, dawn to triumph'
`director_mode`	string	Mode id or `auto`
`brand_id`	string	Locks the BRAND_BLOCK + product hero from Brand Memory
`model_override`	string	Pin any model; omit to let the router choose
`duration_seconds`	number
`shot_count`	number	3 to 5, default 5
`likeness_consent`	boolean	Attest rights/consent for any real person depicted

generate_video_staged

The pro two-stage LOOK LOCK flow: Cadenza directs the shot, locks the look as a cheap inspectable hero-frame image first, then animates that exact frame with the strongest reference-driven image-to-video model. The still is returned too, so the look is correctable before video spend. Best for product shots and brand films where the look must be exact.

Parameter	Type	Notes
`raw_intent`	string, required
`director_mode` / `brand_id`	string	As in generate_video
`model_override`	string	Pin the VIDEO model
`image_model_override`	string	Pin the IMAGE model for the hero frame
`multi_shot`	boolean	true = full arc directed around the locked frame
`shot_count` / `duration_seconds`	number
`likeness_consent`	boolean

animate_image

Animate your own image (product shot, character still, artwork). The image is locked as the continuity reference so the render stays faithful to it; routing prefers the strongest image-to-video model. Default is one faithful cinematic shot; multi_shot directs a 3-shot arc around the asset.

Parameter	Type	Notes
`image_url`	string, required	https URL, `data:image/…`, or a `cadenza://` asset ref
`raw_intent`	string	How to animate it; defaults to a premium cinematic move
`multi_shot`	boolean	3-shot arc, image locked everywhere
`duration_seconds` / `model_override` / `likeness_consent`

ad_from_url

Paste a product URL: Cadenza extracts it into Brand Memory, locks the real product as a continuity reference, and directs an on-brand ad. Extraction is a draft you can correct; the tool degrades with a clear message if the page cannot be read.

Parameter	Type	Notes
`url`	string, required	The product or shop page
`raw_intent`	string	Optional creative direction
`director_mode`	string

refine_shot

Channel-scoped refinement: regenerate one shot with a requested change while the other shots stay stable under the same locked look. A lighting note should never replace the actor, and here it cannot.

Parameter	Type	Notes
`raw_intent`	string, required	The originating sequence intent
`shot_id`	string, required	e.g. `s3`
`change`	string, required	What to change about that shot
`director_mode` / `brand_id`	string

extend_sequence

Add shots to a sequence; new shots inherit the locked character, style, and lighting references so nothing drifts.

Parameter	Type	Notes
`raw_intent`	string, required	The originating sequence intent
`add_shots`	number	Default 1
`current_shots`	number	Default 3
`director_mode` / `brand_id`	string

Brand Memory tools (free)

list_brand_profiles lists your saved brands. set_brand_profile saves or updates one: brand_name (required), palette_hex, cta_text, wordmark_asset_ref, language, product_ref (a hero image locked as the continuity reference). The saved BRAND_BLOCK is a hard lock; the creative layer can never overwrite it.

Publishing tools

publish_video

Two-phase by design. Call WITHOUT confirmations to get per-platform previews (aspect, caption draft, hashtags) for TikTok, YouTube Shorts, Instagram Reels, and Facebook. Call again WITH confirmations to post only the platforms you explicitly confirm. Posting is never autonomous, and an asset without its C2PA manifest id (proof it passed the Output Guard) is refused.

Parameter	Type	Notes
`asset_url`	string, required	The rendered asset to post
`intent`	string, required	Drives the caption draft
`c2pa_manifest_id`	string	Required to actually post: the safety gate
`end_state` / `brand_name` / `cta`	string	Caption seeds
`targets`	string[]	Platforms to preview (default all four)
`confirmations`	object[]	`{platform, confirm: true, caption?, hashtags?}` per platform

list_publish_connections shows which platforms this account has connected and which are linkable.

Conventions that hold across every tool

Scopes are least-privilege: read for listings and plans, generate for billable work, brand for Brand Memory writes, publish for posting. A mis-scoped key gets a clear 403, not a silent failure.
Errors are structured (unauthenticated, blocked, render_failed, scope messages); see Troubleshooting.
Model names are data, not code: list_models is always current, so never hard-code a model id into an automation.
The server's instructions tell compliant clients to plan before generating and to treat publishing as confirmation-gated; a well-behaved agent asks you before spending.