Skip to main content
Glama

Add kinetic text

add_kinetic_text

PROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. CHOREOGRAPH THE SPOKEN WORDS onto the screen in ONE pass — the signature move of top creator reels: each phrase of the transcript appears AT the instant it is spoken, placed in the empty space around the speaker, alternating sides, animated, and holding until the next phrase replaces it. Use it for 'edit this' talking-head footage, promo/educator reels, and whenever the house style calls for speech-carried typography — instead of dozens of add_text calls. start/end (PROGRAM seconds) scope it; default whole program. emphasis_words get the accent color, a size bump and a pop. zone: 'upper' (beside/above the head — default), 'lower', 'sides'. Mutes bottom captions over its window so words never print twice. Each phrase is a normal text item — inspect with get_edl, remove_text by id, or remove and re-run to restyle. AFTER rendering, LOOK at the frames: wrong zone for this framing -> re-run with another zone. motion_style='composed' (default) uses one restrained settle language across the pass and a controlled overshoot only for semantic emphasis; 'preset' restores the legacy named entrances; 'still' removes phrase animation.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
endNo
fontNo
zoneNo
colorNo
startNo
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.
size_scaleNo
accent_colorNo
motion_motifNoActive Blueprint motion motif id this event executes; never 'hold'.
motion_styleNo
emphasis_wordsNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Annotations are all false (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), so the description carries the full burden. It discloses that the tool is project-scoped (only acts on explicit project_id), that it mutes bottom captions over its window to avoid duplication, that each phrase becomes a normal text item (inspectable via get_edl, removable via remove_text), and that motion_style has three distinct behaviors (composed, preset, still). It even warns that the agent should visually verify the zone after rendering and re-run if needed. This is exemplary transparency beyond annotations.

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 long but well-structured, starting with the core purpose, then usage context, then parameter behavior, then post-render workflow. Every sentence adds value; there is no filler. It is not concise in word count, but it is efficiently organized and front-loaded with the most critical information. The length is justified by the tool's complexity (11 parameters).

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?

For a tool with 11 parameters, no output schema, and no nested objects, the description is remarkably complete. It covers purpose, usage conditions, parameter semantics, behavioral side effects (caption muting, text item creation), and even the verification workflow (look at frames, re-run with another zone). It also explains how to inspect or remove the generated text items. Nothing essential for correct invocation or post-call evaluation is missing.

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 description coverage is only 18%, so the description must compensate. It does explain the semantics of start/end (program seconds, default whole program), emphasis_words (accent color, size bump, pop), zone (upper default, lower, sides), and motion_style (composed, preset, still). It does not detail font, color, size_scale, accent_color, or motion_motif, but the most impactful parameters are covered. For the low schema coverage, this is a strong effort, though not exhaustive.

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 opens with a clear verb-resource statement: 'CHOREOGRAPH THE SPOKEN WORDS onto the screen in ONE pass.' It explicitly contrasts with the alternative of dozens of add_text calls and specifies the use cases (talking-head footage, promo/educator reels, speech-carried typography). This sharply distinguishes it from sibling tools like add_text, add_captions, and set_text_motion.

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?

It states precisely when to use the tool (for speech-synced typography over talking-head footage, promo/educator reels) and when not to (instead of dozens of add_text calls). It also provides post-render guidance: inspect frames, and if the zone is wrong, re-run with another zone. The description names alternatives and the conditions that select this tool, leaving nothing to inference.

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.