Skip to main content
Glama

Add captions

add_captions

PROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. Burned captions. mode='from_transcript' (word-timed from the real transcript, recommended) or mode='off', or items=[{text,start,end,style?}] (source seconds) for text the user dictates. PREMIUM PRESETS (style.preset) are professionally designed looks with real fonts. SAFE DEFAULTS: 'clean' (white Plus Jakarta Sans, complete short phrases, size-only hierarchy), 'documentary' (restrained subtitles on a translucent contrast panel), and 'broadcast' (left-aligned news/explainer lower third). SOCIAL/CREATIVE: 'reels' (FLAGSHIP short-form system: tight two-line hierarchy, warm hero word and multi-stage elastic word landings), 'podcast' (bold white words land on screen as spoken, keywords light up in the accent color, get a highlight box or serif italics, numbers render HUGE), 'beast' (loud MrBeast-style: ALL-CAPS impact font, centered, the spoken word pops in the accent color), 'karaoke' (an accent box follows each spoken word), 'spotlight' (ONE glowing word at a time, centred, uppercase — the modern single-word look for hype/motivation/fast talking; the ONLY preset that belongs mid-frame), 'elegant' (calm lower-third, serif-italic accents — interviews/luxury), 'lyric' (phrase-led music/quote typography), plus stacked/iridescent/chrome/editorial/fashion/luxe/impact/retro/neon composed looks; 'classic' is the plain legacy look. MOTION LOOKS (style.motion_look, browser-drawn, the premium default where available): 'editorial' (bold grotesk + big serif-italic emphasis word tucked above/below the line, hard pops — podcasts, reels, premium), 'clean' (calm sentence case rising out of a blur — interviews, tutorials), 'lockup' (small caps connectors over ONE huge hero word), 'pop' (outlined hype punches), plus box/serif/glow/stack/mono; words reveal in place on their spoken onset and phrases clear on pauses. If style is omitted, the tool chooses a coherent treatment deterministically from the measured format, speech pace and brief (a motion look for short-form/podcast/premium briefs, with the preset kept as the fallback) — it does not make every project wear the same caption skin. PLACEMENT: multi-word presets default to the BOTTOM, clear of the face — do not move them to 'middle'; only a single-word-at-a-time look may sit centred. With a preset, sparse emphasis is AUTO-SELECTED from the KEPT transcript when emphasis_words is omitted; measured vocal stress leads on short-form/cached audio, with numbers and semantic outcome words as fallback. pass a verbatim list only when specific words are required, or [] to explicitly disable hierarchy. highlight_color sets the accent (default warm yellow); uppercase overrides the preset's casing; position bottom/top/middle overrides its placement and LOCKS that band for the whole video (no shot-by-shot position changes); anchor_y similarly locks an exact vertical frame fraction. Omit both to let collision-aware placement adapt by shot. Other style fields: color '#RRGGBB', size s|m|l|xl (presets are already big at 'm'), size_scale 0.5-3.0, dynamic:true (legacy karaoke, no preset), animation fade|pop|slide_up|punch|blur_in|whip|flash|rise|drop|elastic|bounce|swing|zoom_blur, or 'none' to turn a preset's animation OFF (instant words), single_line:true to guarantee one rendered row per transcript-caption state regardless of the preset's normal flow/stack layout, max_words_per_caption 1-16. Without a motion look the default modern preset is 1-2 words at a time, stacked levels, fade in (preset 'stacked', max_words_per_caption 2) — not a sentence subtitle; a motion look groups its own phrases (pass max_words_per_caption only to narrow them). Example — premium reel captions: {mode:'from_transcript', style:{motion_look:'editorial', preset:'stacked'}}. Example — dictated title card: {items:[{text:'CHAPTER ONE', start:0, end:2.5, style:{preset:'beast'}}]}. Stack presets (stacked/iridescent/chrome/fashion/luxe/editorial/impact) compose 1-2 words across lines of very different SIZES; font picks a bundled family, emphasis 'big' enlarges keywords WITHOUT recolouring them, leading below 1.0 overlaps the lines so a smaller word fades in behind the hero. Production controls include outline_color/outline_width, shadow, background_color/background_opacity, tracking and text_align.

Input Schema

NameRequiredDescriptionDefault
modeNo
itemsNo
styleNo
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.
motion_motifNoActive Blueprint motion motif id this event executes; never 'hold'.
emphasis_wordsNo
max_words_per_captionNo
min_words_per_captionNoPreferred minimum for static phrase presets such as clean; QA flags unavoidable fragments.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • addedInput schema / properties / style / properties / leading / maximum
      Added value: +2.2
    • addedInput schema / properties / style / properties / leading / minimum
      Added value: +0.5
    • addedInput schema / properties / style / properties / motion_look
      Added value: +{
      +  "description": "Browser-drawn caption look, the default for short-form/podcast/premium: editorial = bold sans + big serif-italic emphasis word, hard pops; clean = calm sentence case rising from a blur; lockup = small caps over one huge hero word; pop = outlined hype punches; box = gliding highlight pill; serif = gold serif-italic emphasis; glow = karaoke; stack = giant condensed hero; mono = typewriter. null = presets.",
      +  "enum": [
      +    "editorial",
      +    "clean",
      +    "lockup",
      +    "pop",
      +    "box",
      +    "serif",
      +    "glow",
      +    "stack",
      +    "mono"
      +  ],
      +  "type": "string"
      +}
  2. Changed1 schema field changed
    • changedInput schema / properties / style / properties / preset / enum
      Previous value: -[
      -  "clean",
      -  "documentary",
      -  "broadcast",
      -  "retro",
      -  "neon",
      -  "podcast",
      -  "reels",
      -  "beast",
      -  "karaoke",
      -  "elegant",
      -  "spotlight",
      -  "stacked",
      -  "iridescent",
      -  "chrome",
      -  "editorial",
      -  "fashion",
      -  "luxe",
      -  "impact",
      -  "lyric",
      -  "classic"
      -]New value: +[
      +  "composed",
      +  "clean",
      +  "documentary",
      +  "broadcast",
      +  "retro",
      +  "neon",
      +  "podcast",
      +  "reels",
      +  "beast",
      +  "karaoke",
      +  "elegant",
      +  "spotlight",
      +  "stacked",
      +  "iridescent",
      +  "chrome",
      +  "editorial",
      +  "fashion",
      +  "luxe",
      +  "impact",
      +  "lyric",
      +  "classic"
      +]
  3. First observed

TDQS

A3.9/5.0
Behavior4/5

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

Annotations only declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the description usefully adds that the call is project-scoped and returns project identity, that it deterministically auto-selects a treatment when style is omitted, and that position/anchor_y 'lock' placement for the whole video. It does not state what happens to pre-existing captions or whether repeated calls stack, which is a real gap for a non-idempotent mutation.

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?

This is a ~600-word wall of prose with no bullets, paragraphs or line breaks, forcing an agent to parse dense run-on sentences to find anything actionable. Capitalized section markers (PROJECT-SCOPED, PREMIUM PRESETS, MOTION LOOKS, PLACEMENT, SAFE DEFAULTS) give some structure, but the sheer length and lack of scannability are a serious usability defect for a tool description.

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 a complex tool with 8 parameters and a ~22-field nested style object plus no output schema, the description covers an unusually complete surface: modes, preset catalog, motion looks, default-selection behavior, placement rules, emphasis auto-selection, production controls, and two worked examples. Nothing an agent needs in order to invoke it correctly appears to be missing, even if the presentation is unwieldy.

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 38% and enums carry no descriptions, so the description must compensate — and it largely does, explaining mode values, items shape, the meaning of every major preset and motion_look, plus style fields like highlight_color, uppercase, single_line, size_scale, animation and max_words_per_caption. Coverage is broad but not exhaustive (e.g. outline_color/outline_width/shadow/background_* are only name-dropped), and it does not cover min_words_per_caption or motion_motif beyond the schema text.

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?

The description states a specific verb and resource — 'Burned captions' — and pins the scope ('acts only on the explicit project_id and returns the project identity with its result'). An agent can tell it produces burned-in captions, but the purpose sentence is buried under a torrent of preset/motion detail rather than front-loaded, and it never explicitly distinguishes itself from siblings like add_text, set_caption_style or audit_captions.

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?

There is substantial usage guidance: mode='from_transcript' is marked recommended, emphasis_words should be passed verbatim 'only when specific words are required, or [] to explicitly disable hierarchy', and multi-word presets 'default to the BOTTOM... do not move them to middle'. It lacks explicit when-to-use-this-vs-alternative-tool guidance and any exclusion conditions, so it stops short of a 5.

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.