Synthesia

Part of the classic Synthesia flow (deprecated): only for a classic video (one the user explicitly asked for, or made because whoami's top-level `syren_available` is false), never for a Synthesia Syren video. Fetch one page of templates for the "Set up video" widget's picker, or search them by name. Pagination helper for the widget's picker — it lazy-loads more templates as the user scrolls, on both tabs. NOT needed for normal create-from-script calls (get_brand_context already returns the first page of the Synthesia tab, plus its cursor). Returns `{templates, next_cursor}`; `next_cursor` is null on the last page, and always null for a search.

list_templates

Classic Synthesia flow: covers classic videos only, never Synthesia Syren videos (list those with syren_list_videos and open one with syren_show_video). Search the user's existing Synthesia video library. Use this to answer questions about videos that already exist — "which videos in the onboarding programme are published?", "what have we made on data privacy?", "show me my recent drafts". Not for creating videos. This is KEYWORD search, not semantic: pass the salient terms from the user's question, not the whole sentence. Results are always scoped to what the authenticated user can access, so videos they can't see in the Synthesia app are never returned. Searches exactly ONE workspace and never aggregates across them, including the user's private "My Videos" space within it — each row's `visibility` says which. To cover several workspaces, call this once per `workspace_id` and aggregate the results yourself. With more than one workspace and none established, this returns `needs_workspace_selection` instead of results — ask which workspace, then call again.

search_videos

Classic Synthesia flow (deprecated): only use it when the user explicitly requests a classic video or the classic flow, or whoami's top-level `syren_available` is false; else use syren_create_video. Open the interactive video setup widget — the primary entry point for creating an editable classic Synthesia video draft. Requires a paid Synthesia plan: a free-plan workspace is refused and nothing is created. Applies when the client can render web widgets (ChatGPT, Claude desktop): it opens a picker where the user confirms or adjusts the workspace, template and brand kit, then "Create draft" calls the right create_video_* tool for them. Without widgets (a terminal or CLI agent), call `create_video_from_prompt` / `create_video_from_script` directly. YOU choose the creation path via `mode` (or by which of `script` / `prompt` you pass) and the user CANNOT change it in the widget, so when it is unclear whether they have a finished script or want one written, ask them BEFORE calling this. Default to "prompt" — treat the input as a brief for the Assistant to develop — and use "script" only when the user explicitly says the text is already written: • "Create a video about the history of Denmark" → prompt • "Turn this slide deck into a video" → prompt • "Here's my finished narration, make a video" → script Call this EXACTLY ONCE per request with the user's COMPLETE input as one string, never per scene: repeat calls render several widgets and create several videos. On "Create draft" the widget runs the create itself, tracks the build and reports the outcome. You get no `conversation_id` / `video_id`, so never poll `get_video_draft_status` for it. The widget shows your selections pre-filled and the user acts on it directly, so keep your reply to one line or nothing. Do not list the workspaces, brand kits or templates, walk through the steps, or offer to adjust the script — that pushes the widget out of view and contradicts what they see.

setup_video

Answer the question Synthesia Syren's agent is waiting on (state `needs_answer`), then keep calling syren_get_status with the returned `cursor` until `state` is `done`, `needs_answer` or `halted`, and only then tell the user the result. The answer resumes its work; this returns at once and shows the player. Pass option labels in `choices`, free `text`, or both. Changes are saved as versions; an earlier one can be restored by asking for it with syren_edit_video.

syren_answer_question

Carry on a Synthesia Syren turn that stopped short, above all one a status reports as `halt_kind: "interrupted"` (Syren's server restarted mid-turn) or one halted only because Syren's last edit wasn't checked (`halted.reasons` just `unchecked`, so no preview), then keep calling syren_get_status with the returned `cursor` until `state` is `done`, `needs_answer` or `halted`, and only then tell the user the result. For those two, call it once without asking the user; for any other halt, only when the user wants to carry on. It sends the director's own resume message (`halted.resume`), so the agent picks up where it stopped. Returns at once and shows the player. Refused with `accepted: false` and a `reason` when nothing is halted: `turn_running`, `question_pending` (answer it with syren_answer_question) or `not_halted`. Changes are saved as versions; an earlier one can be restored by asking for it with syren_edit_video.

syren_continue

Make a video (up to 3 minutes) with Synthesia Syren (Beta) from a brief, the default for every new video unless the user explicitly asks for a classic video, only when whoami's top-level `syren_available` is true, then keep calling syren_get_status with the returned `cursor` until `state` is `done`, `needs_answer` or `halted`, and only then tell the user the result; don't open a second player with syren_show_video unless the user says they can't see it. A turn often takes 5 to 15 minutes; don't stop early, and if you do, never say the player will update on its own, say they can ask you to check. Syren designs the visuals, on-brand too (put the brand in `brief`; brand assets can be uploaded in Synthesia Syren); the user edits in the chat. Before the first, tell the user once that Syren is in beta, makes videos up to 3 minutes, uses credits and can't be opened in the classic editor. Then, unless the request already settles it, ask ONE short multiple-choice round on creative direction: an on-screen presenter or not, generated imagery or b-roll clips or motion graphics only, background music and its mood, visual style or palette, length and aspect, each with a default they can accept ("or I can pick for you"). Skip what they already said, never ask a second round, and if they say "just make it", go ahead with sensible defaults. Put the answers in `brief`: without them Syren's agent makes voice-over and kinetic type only. Later changes go through syren_edit_video with the same `conversation_id`; to reopen a video use syren_show_video, as this tool always starts a new conversation. A new video goes to the user's My Videos (`destination`), or the team workspace when that isn't available. If a workspace admin turned Syren off, this says so and offers the classic flow instead.

syren_create_video

Change a Synthesia Syren video by sending an instruction to the conversation that made it, then keep calling syren_get_status with the returned `cursor` until `state` is `done`, `needs_answer` or `halted`, and only then tell the user the result. Every change is saved as a new version and nothing is lost: to undo, call syren_edit_video again with e.g. "undo that" or "go back to the previous version", which restores it as a new version. When the user asks for a look-and-feel change without saying what (a presenter, generated imagery or clips, music, style), offer one short round of concrete options with a default first, then send their pick as the instruction. The agent keeps the whole history. Returns at once and shows the player. While a turn is still running, or the agent is waiting on an answer, the instruction is refused with `accepted: false` and a `reason`.

syren_edit_video

Start rendering the full-quality video file of a Synthesia Syren video, when the user wants the finished download, then follow it with syren_get_export_status. The file every finished turn gets automatically is a quick preview (`video_quality`); this renders the video as it is now at its own size and frame rate, which takes render capacity, so only on request. It returns at once: `exporting` (follow with syren_get_export_status, same arguments; `export.phase: waiting` when another render of this version goes first), `done` with `video_url` when that version is already exported, or `failed`. Calling it again joins the same render rather than starting another (and repeats a failure of this version), so it is not how to follow it; call it once more only when the status goes from `waiting` to `none`, which is when the render starts. `available: false` with a `reason` when there is no video yet or this Syren deployment can't export.

syren_export_video

Check the progress of a Synthesia Syren video file export (one syren_export_video started) without starting one, to follow it until `done` with its `video_url`. Pass the same arguments as syren_export_video. Returns `exporting` (with `export.phase` and `export.progress` when known; check again in a few seconds), `done` with `video_url`, `failed`, or `none` when the video as it is now has no export at that quality. If it goes from `export.phase: waiting` to `none`, call syren_export_video once more: the render starts then (another render of the same version went first). `available: false` with a `reason` when there is no video yet or this Syren deployment can't report it.

syren_get_export_status

Look at a Synthesia Syren video at one moment: the frame at `at_seconds` comes back as an image, for describing or discussing what is on screen there without sending Syren's agent a turn. It shows the video as it is now (its latest revision). `available: false` with a `reason` when the conversation has no video yet or this Syren deployment can't render a frame.

syren_get_frame

Wait up to about 15 seconds for Synthesia Syren's agent, then say where it stands: `running`, `needs_answer` (a `question` with options), `exporting` (the video file is rendering), `done` (its `reply`, frames of the video as images, and `video_url` when exported; the player in this conversation updates itself, so call syren_show_video only if the user says they can't see it) or `halted` (why it stopped short). Pass back the `cursor` each call returns, and keep calling until it is `done`, `needs_answer` or `halted`: a turn commonly takes 5 to 15 minutes. If you stop first, never say the player will update on its own; say they can ask you to check.

syren_get_status

The videos in a Synthesia Syren workspace, the user's own My Videos and the team's, for having Syren's agent work on one that exists. Each video's `location` says which: `my_videos` or `team`; its `conversation_id` opens it with syren_show_video.

syren_list_videos

List the user's workspaces. Invoked by the interactive setup widget, not the model. Returns ``{workspaces: [{id, name, can_create, plan_tier, capabilities}]}`` — the SAME workspace entries `whoami` returns, minus the identity payload around them. The widget calls it to resolve a workspace id when the host hands it no context. It does not read the entitlement fields today: the brand-kit gate it acts on is `workspace_brand_kits_available` from `get_brand_context` (DP-1408). They are here so one workspace shape serves both tools. `can_create` is a role/license permission, NOT a plan check: creating or generating videos also requires a paid Synthesia plan, so a free-plan workspace is refused (`plan_forbidden`) even where `can_create` is true. `studio_url` links to the Synthesia app for this environment, so the widget can offer "Open Synthesia" when the list is empty (a brand-new account still provisioning, MCP-237) without hardcoding a host that differs between dev and prod. It carries the caller's `login_hint` like every other link this server hands out (DP-1606), so a user with no browser session lands on their sign-in method rather than the login wall.

list_workspaces

Widget-only: tell Synthesia Syren whether the user's player is playing or paused at a moment, so Syren's agent can see where they are; a no-op where Syren doesn't take it.

syren_report_viewer

Open the player, without starting a turn or a new conversation, on a Synthesia Syren video from an earlier conversation or session (one the user asks to see, open or show, found with syren_list_videos), or when the user says this conversation's player is missing or broken (they can't see it, or it shows an error); never right after syren_create_video or syren_edit_video in this conversation, whose player updates itself. Pass the `conversation_id` that made it. Returns where the conversation stands now (as syren_get_status does, without waiting) and the `cursor` to follow it from.

syren_show_video

Stop Synthesia Syren's agent mid-turn, when the user asks to. What it already changed in the video stays; the conversation can carry on with syren_edit_video.

syren_stop

Record a setup-widget funnel event for analytics. Invoked by the widget, not the model.

track_widget_event

Identify the user and list the workspaces they can work in — call this first. Returns the caller's identity plus their workspaces. Every tool call is scoped to ONE workspace (`workspace_id`) — nothing aggregates across them. Establish the active workspace once from `workspaces` (auto when there's only one; otherwise ASK the user which to use — do not guess), then reuse that `workspace_id` for the session unless the user asks to switch. `workspaces` is `[{id, name, can_create, plan_tier, capabilities}]` — the team workspaces the user shares with colleagues, which is what "the workspace I'm in" means. `plan_tier` is "free" / "self_serve" / "enterprise" ("none" = no valid plan, "unknown" = couldn't be resolved); `capabilities` lists granted feature names such as "brand_kits" (null when unresolved). Both describe THAT workspace's plan — don't offer features its capabilities don't include, and never infer entitlement from data shape (an empty brand-kit list may just be an unconfigured enterprise workspace). `can_create` reflects role/license, not plan: creating also needs a paid plan (a free-plan workspace is refused). Videos created here land in the user's private "My Videos" WITHIN the chosen team workspace, and `search_videos` covers it too — the team workspace id is still the one to pass everywhere. If the backend can't be reached this call fails with a retryable error rather than returning an empty list: retry. An empty `workspaces` carries a `note` with the cause and the fix; `workspace_state` names it: `no_workspace_yet`, `should_join` (an invitation to accept), `awaiting_invite` (an admin must invite them) or `restricted_access` (an admin blocked the app). Top-level `syren_available` false: Syren is off for this user (admin or outage); never call syren_* tools. Per workspace: whether Syren takes that id. Credits: `syren_credit_source` is the active pool, "free" (`syren_free_credits_left`) then "workspace" (`syren_workspace_credits`); say which (~1,000-2,000 per video minute).

whoami