Skip to main content
Glama

Get a video project

get_studio_video
Read-onlyIdempotent

Where a film is. storyboard: its version (send it to edit_studio_video_storyboard), scenes (each id, n, type, seconds, what we see, what is say-d, the on_screen words, status made / changed / making / failed / new, a picture_url, on a filmed scene its storyboard_sheet_url (the sheet of its key moments the scene is made from — show it; redraw it free with edit_studio_video_storyboard redraw_storyboard), and on a scene that copies a video's moves follow: the part it copies (from/to), its line and the other parts it may follow (choices)), things (people, places, products, style), layers (music, voice — with voice.take { url, seconds, stale } once the voiceover is recorded, to play to the user — captions, and the film's pace, punchy or calm), script_options (other versions of the script; pick one with edit_studio_video_storyboard pick_script_option), still_missing (what the director will choose if nobody does) and undo. button: the film's one button — its label and hint exactly as the user sees them, its price in credits with the lines it is made of, the quote_hash, step (film = this press makes the film; on a narrated film voice_with_film: true means the voiceover is recorded in the same press and the scenes are cut to it — its price is already in credits and lines, so it is ONE press. voice_first, when present, is the opt-in two-press way for a user who asks to hear the read before any picture: its own label, credits and quote_hash record only the voiceover, and the film after it costs about film_after_voice_credits. voice = an older quote with no one-press price: this press records only the voiceover; voice_after = an ad or reel shot picture-first: its picture is done and this press records the voiceover fitted to it and puts it on the film, with any lines_too_long to shorten first), nothing_to_make, the allowance for fixes (budget) and making.stoppable while a press is making. Before make_studio_video the user must see that price: in a chat with approval cards, propose make_studio_video and the card shows it (never write the label as text); otherwise show them the label and the lines first. Also: status, the timeline (each clip's kind, duration, status, its file as url and a file_name to save it under; for a transparent drawn graphic transparent.mov_url / transparent.webm_url; a separate-clips shot is delivered trimmed to its planned length and usually without sound, so url is that delivered file only once it is ready, full_take_url/full_take_file_name the take as generated, and delivery.state one of finishing, finishing_late, delivered, as_generated), an older film's plan waiting for approval (pending_plan with proposal_id, quoted_credits and its price_lines), drawn_on_film (motion_graphics: playing = a motion-graphics edit plays with its captions and closing card in the picture, kept = taken off and kept to put back, null = none; layers: each overlay layer — captions, end_card, hook_title, lower_third, logo, drawing — with what it shows; put_back_available: what the last removal took off. To change any of it, ask in studio_video_message — "remove the motion graphics", "put the graphics back", "remove the extra captions" — free, at once), the director's last reply (last_reply, written at last_reply_at) and question, a rough_cut (several of their clips: joined or not, and what next), and export.url once the film is put together (ready: true). On a connection with a daily Creative Credit cap, daily_cap shows remaining_today and whether it covers_button / covers_pending_plan, editing_budget shows the persistent automatic-edit cap, revision, used/reserved/available credits, and latest charge state. An active cap authorizes requested paid edits within its remaining amount; it is not a charge or future reservation, and unused credits are never charged. daily_cap still shows the connection's separate daily Creative Credit limit. Poll about every 30 seconds while making. Does not spend.

Input Schema

NameRequiredDescriptionDefault
user_goalNoOptional: the user's goal behind this call, in one short sentence of plain words (e.g. "add a page so customers can book tables"). No names, emails or other personal details.
project_idYesProject id from create_motion_project. The bare project id or the library id ("studio-video:<uuid>" from list_creations / find_creation) both work.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / user_goal
      Added value: +{
      +  "description": "Optional: the user's goal behind this call, in one short sentence of plain words (e.g. \"add a page so customers can book tables\"). No names, emails or other personal details.",
      +  "type": "string"
      +}
  2. Changed3 schema fields changed
    • changedInput schema / properties / project_id / description
      Previous value: -"Project id from create_motion_project"New value: +"Project id from create_motion_project. The bare project id or the library id (\"studio-video:<uuid>\" from list_creations / find_creation) both work."
    • removedInput schema / properties / project_id / format
      Removed value: -"uuid"
    • addedInput schema / properties / project_id / pattern
      Added value: +"^(?:studio-video:)?[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
  3. First observed

TDQS

B3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real context beyond that: 'Does not spend' clarifies it is free against Creative Credits, and the polling cadence implies a request-rate expectation. It does not state whether the snapshot is consistent or how large the response can get, which is the main remaining behavioral gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One enormous unbroken paragraph mixing a data dictionary of returned fields with the few operational rules that actually govern invocation. Critical instructions ('Does not spend', 30-second polling, price-before-make) land at the very end, and field-level minutiae like transparent.mov_url and delivery.state crowd out the front-loaded summary an agent needs. Size is defensible only because no output schema exists, but the structure is poor.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description carries the entire return-value burden and does so thoroughly, documenting storyboard scenes, button pricing/step states, timeline delivery states, drawn_on_film, daily_cap and editing_budget. Given the tool's complexity, this is close to complete; only clarity of presentation, not breadth, is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and both parameters are documented in the schema itself (project_id's dual bare/library-id format, user_goal's privacy constraint). The description mentions neither parameter, so it adds nothing here; the baseline 3 applies when the schema carries the burden.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening 'Where a film is' is evocative but not a verb+resource statement; an agent infers 'read the state of a video project' only after parsing the enumerated fields. The enumeration itself (storyboard, button, status, timeline, export) makes the resource scope clear, and edit_studio_video_storyboard / make_studio_video / studio_video_message are named as the tools for changing things. The core purpose is recoverable but never stated plainly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Operationally important guidance exists but is buried mid-paragraph: 'Poll about every 30 seconds while making', the rule that the user must see the price before make_studio_video (propose the tool so the approval card shows it), and 'To change any of it, ask in studio_video_message'. These are genuine when/when-not rules, but they are interleaved with field documentation rather than stated up front, so an agent must read the entire block to find them.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources