Skip to main content
Glama

Add motion graphic

add_motion_graphic

PROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. Place a browser-rendered, After-Effects-grade motion graphic on the PROGRAM clock: spring/blur entrances, glow, gradients, 3D depth, masks, icon/emoji pops, counters, UI cards. One call = a finished composition, silent by default; pass sfx=true only for a moment that earns sound (its template cues map to the approved sound library and are levelled against the voice at their landings; CHECK lines flag a bright cue on a payoff word's onset or more than 1-2 sounds in a talking short). start/end are program seconds; end defaults to the template's natural duration. Cue it to the exact word/beat it amplifies (use word times from get_kept_transcript). layer='above_captions' (default for designed moments) or 'below_captions'. layer='behind_subject' is the premium depth signature: the graphic (a giant hero word, a number, a shape) is drawn INTO the shot and the speaker stays in FRONT of it — the person is measured out of the footage like add_text_behind (same rules: one continuous take, no speed ramp, >=0.4s; refused with the measured reason when there is no clear subject), and the reply reports how much of the graphic the subject crosses. Use it for 1-2 hero moments per short, with BIG type placed where the speaker's head/shoulders cross it. CAPTIONS: leave mute_captions unset — the captions drop exactly the spoken words this graphic shows (its number, slammed word, quoted kicker or rows) and keep every other spoken word (every heard word reaches the screen once — a lockup's rows no longer get micro bridge lines: the words they leave out are captioned beside it), moved to a band clear of the box it draws, the face and any card layout while it is up; the reply NOTEs the words captioned beside it and the words it must mute because no band is clear (then carry them on it, e.g. as a kicker, or move it off the caption band). mute_captions=true no longer hides a whole window; false keeps them all running (a number or starred word it shows is still not repeated). template='html' takes your own HTML/CSS/JS on the MG runtime in html. The write is rejected if the composition errors or draws nothing. HEADLINE BAND: template='headline' is PERSISTENT — the standing claim headline of a card or letterbox layout, one per program (end omitted = the program end; y omitted = centred in the free band above the card or picture). It yields its band on its own at render time (fades out before any graphic in the band lands, back after it leaves), never mutes captions and is silent; the reply lists the windows it yields. FACE KEEP-OUT: the write measures where the graphic draws against the speaker's face and mouth over its window (through the crop, zooms and cards) and the 9:16 safe area (6% side margins, the right 12% clear between y 0.5 and 0.85, nothing below y 0.80); a graphic that covers the face or leaves the safe area is MOVED to the nearest clear zone with its own y (and x/align/side where it has them) — above the head, below the chin, beside the face — and the reply says what moved (KEEP-OUT) or why nothing fits (NOTE). allow_face_overlap=true keeps a deliberate design over the face. NUMBERS land on their word: a counter completes 20 ms before its spoken number's onset in the transcript (the write sets its land; a count really counts, 0 -> value over ~0.4 s into the word, its window opening 0.45 s before it so it never runs across the setup; a 'reveal' starts on the word; a spoken range is value '30–40', each figure landing on its own word) and a word_slam whose hero is a figure ('32%', '$1.2B'; not a name like 'GPT-4') moves onto it — the reply says NUMBER LANDED, and NOTEs a moved window that now overlaps a neighbour. THE WINDOW: a word-timed graphic (phrase_build, marker_text over a spoken line) starts on its first visible word (WINDOW), and an entrance or exit within 0.15 s of a cut moves onto the cut frame so the change is one event (CUT-SNAP; never more than 0.15 s off its word; a number's entrance stays on its number). ONE TYPE SYSTEM: an accent/color you do not pass comes from the short's Look (the captions' highlight colour, else the accent its graphics wear; LOOK in the reply), and the reply NOTEs (look) a second accent, a fourth type role or broadcast furniture in an editorial Look, with the fix. phrase_build sets only its rows (at most 4, at most 3 sizes: SIZES); back-to-back slams of one style are a SERIES sharing one size per line. TIERS (word_slam tier, optional): 'hook' is the opening title as a headline (main line at 7%+ of the frame height, lead-in small above it) that owns its zone: the captions wait until it exits (HOOK; mute_captions=false keeps them); 'payoff' locks a number and its noun up in the accent ('140 / characters') — the short's largest lockup (NOTE (payoff) names a taller one); 'hero' is ONE giant word per short, behind the speaker by default on a measured person matte, drawn as a face-safe display slam above the picture when no person matte can be had (HERO FALLBACK). THE COVER (one call): template='cover_headline', start=0, end ~2.5-3, params {text: a strong curiosity title, 3-10 words, stars for the accent} sets the short's opening frame as a thumbnail: huge centred condensed caps, complete on frame 0, then it fades into the talk; it owns its zone like the hook tier (the captions wait until it exits; COVER). For SOME shorts, never every one.

Input Schema

NameRequiredDescriptionDefault
idNo
boxNoOptional capture region hint [x0,y0,x1,y1] frame fractions.
endNo
sfxNo
htmlNo
layerNo
startYes
paramsNoTemplate parameters (see list_motion_templates).
purposeNo
templateYesTemplate name from list_motion_templates, or 'html'.
project_idYesRequired immutable scope for this call. Copy the id from list_projects/open_project/project_state; the active-project pointer is never used to guess.
mute_captionsNoOmit (default): captions drop the words it shows; every other heard word stays captioned beside it. true = the same (no graphic mutes a whole window: every heard word reaches the screen once), muting only where no band is clear of it; false = captions keep running (a shown number/*starred* word is still not repeated).
allow_face_overlapNoKeep a deliberate placement over the face (skips the keep-out move).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / mute_captions / description
      Previous value: -"Omit (default): one reading path, captions drop the words it shows and yield to its phrase until it leaves. true = no captions in its window; false = captions keep running (a shown number/*starred* word is still not repeated)."New value: +"Omit (default): captions drop the words it shows; every other heard word stays captioned beside it. true = the same (no graphic mutes a whole window: every heard word reaches the screen once), muting only where no band is clear of it; false = captions keep running (a shown number/*starred* word is still not repeated)."
  2. Changed1 schema field changed
    • changedInput schema / properties / mute_captions / description
      Previous value: -"Omit (default) for word-level: captions drop only the spoken words this graphic shows. true = no captions for its whole window; false = captions keep running (a number/*starred* word it shows is still not repeated)."New value: +"Omit (default): one reading path, captions drop the words it shows and yield to its phrase until it leaves. true = no captions in its window; false = captions keep running (a shown number/*starred* word is still not repeated)."
  3. Changed2 schema fields changed
    • addedInput schema / properties / allow_face_overlap
      Added value: +{
      +  "description": "Keep a deliberate placement over the face (skips the keep-out move).",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / mute_captions / description
      Added value: +"Omit (default) for word-level: captions drop only the spoken words this graphic shows. true = no captions for its whole window; false = captions keep running (a number/*starred* word it shows is still not repeated)."
  4. Added

TDQS

A4.1/5.0
Behavior5/5

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

Annotations only declare the basic safety profile; the description adds substantial non-obvious behavior: project-scoped return identity, write rejection when the composition errors or draws nothing, caption-drop behavior, face keep-out moves, NUMBER LANDED/CUT-SNAP replies, and headline-band yielding. None of this contradicts the annotations.

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?

The uppercase section labels provide structure, and the core purpose is front-loaded, but the description is extremely long and dense. Several points, especially mute_captions semantics, are repeated from the schema, and the sheer volume of edge cases makes it far from concise.

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

Completeness5/5

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

Given the tool's complexity and lack of an output schema, the description is highly complete: it explains return reporting, caption interactions, face keep-out, number landing, cut snapping, tiers, headline bands, and cover behavior. An agent has enough context to invoke it without surprises.

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

Parameters4/5

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

Schema coverage is only 46%, but the description compensates for most critical parameters: start/end are program seconds, end defaults to template duration, layer values are explained, mute_captions has detailed semantics, and sfx/html/headline/cover parameters are covered. It still leaves id and purpose unexplained, and box is handled only by the schema.

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

Purpose4/5

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

States a specific verb and resource: "Place a browser-rendered, After-Effects-grade motion graphic on the PROGRAM clock." It also clarifies project scoping and output identity, but does not clearly differentiate itself from sibling graphic tools such as add_vector_graphic or add_kinetic_text; it only references add_text_behind as a behavioral analogue.

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

Usage Guidelines4/5

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

Provides rich in-tool guidance: sfx=true only for a moment that earns sound, layer defaults, 1-2 hero moments per short, and cover usage for some shorts but never every one. It lacks explicit tool-level alternatives among the many graphic siblings, so an agent still has to infer when to use this rather than add_vector_graphic/add_kinetic_text.

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.