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. If style is omitted, the tool chooses a coherent preset deterministically from the measured format, speech pace and brief — 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. Default modern look is 1-2 words at a time, stacked levels, fade in (preset 'stacked', max_words_per_caption 2) — not a sentence subtitle. Example — modern reel captions: {mode:'from_transcript', style:{preset:'stacked', animation:'fade'}, max_words_per_caption:2}. 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

TableJSON 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. First observed

TDQS

A4.6/5.0
Behavior4/5

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

With no read-only/idempotent/destructive hints from annotations, the description carries the behavioral burden. It openly states captions are burned, scope is limited to the explicit project_id, and that style omission triggers deterministic preset selection. It does not explicitly mention reversibility or side effects on the source transcript, so a small gap remains against the ideal.

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

Conciseness4/5

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

The description is very long but well-organized with clear section markers for modes, presets, placement, emphasis, and production controls. Examples are concrete and useful. Minor redundancy around preset casing and placement rules slightly reduces conciseness, but every sentence contributes meaningful guidance for a complex tool.

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?

Given the tool's complexity, the description is remarkably complete, covering mode selection, preset defaults, placement, emphasis, animation, and example payloads. It explicitly states the return value is project identity. It does not describe any error cases or output schema, but the absence of an output schema lowers the burden and the stated return value is adequate for a call-level understanding.

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

Parameters5/5

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

Schema coverage is only 38% and several parameters have minimal schema descriptions, but the prose compensates thoroughly by explaining mode, items, style preset behavior, placement fields, emphasis handling, animation options, and production controls. Every major schema parameter is effectively documented in the description, even where the schema itself is sparse.

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

Purpose5/5

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

The description clearly states the tool adds/burns captions onto a project, with explicit modes for transcript-derived or dictated text. It distinguishes itself by emphasizing project-scoped behavior and returning project identity, making the primary purpose unmistakable relative to siblings like set_caption_style.

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

Usage Guidelines5/5

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

The description gives explicit guidance on when to use each mode, recommends 'from_transcript', explains default preset selection when style is omitted, and provides concrete examples for modern reels and dictated title cards. It also clarifies placement rules and when to supply emphasis_words or disable them, leaving little ambiguity.

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.