Skip to main content
Glama

words

Add, change, or remove on-screen text in a video shot using style presets and animations; returns shot and text IDs and creates one undo step.

Instructions

Add, change or remove on-screen text in a shot. preset is one of the style's text presets (its look and font); action is its animation (pop, slam, type, fade, slide, drop...). Ids must come from the current style: call library to see them (a wrong id is refused with the valid list). Returns the shot and text ids. One undo step for the person. For a script line that is spoken, use write_script or assign_line (its captions come from the voice).

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "words"
  }
}

Input Schema

NameRequiredDescriptionDefault
xNoCentre across, in % of the frame (50 is the middle).
yNoCentre down, in % of the frame (18 is near the top; captions sit near 84).
atNoWhen it appears, in % through the shot (0 to 100)
idNoText id, for change and remove.
opNoadd if left out.
fontNoA font family the style offers, or "".
shotNoThe shot's id (from get_project). Left out: the shot on screen.
sizeNo1 is normal.
whenNoRough timing in the shot. Use at for an exact %.
colorNo"#RRGGBB", or "" for the preset's own.
untilNoWhen it leaves, in % through the shot (0 to 100)
wordsNoThe text. Short reads best: 2 to 5 words.
actionNoAnimation id (library text_animations).
presetNoText preset id (library text_presets).
line_wordsNoWords per line (2 if left out).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed7 schema fields changedv0.1.2
    • addedInput schema / properties / action / description
      Added value: +"Animation id (library text_animations)."
    • addedInput schema / properties / op / description
      Added value: +"add if left out."
    • addedInput schema / properties / preset / description
      Added value: +"Text preset id (library text_presets)."
    • addedInput schema / properties / when / description
      Added value: +"Rough timing in the shot. Use at for an exact %."
    • addedInput schema / properties / words / description
      Added value: +"The text. Short reads best: 2 to 5 words."
    • addedInput schema / properties / x / description
      Added value: +"Centre across, in % of the frame (50 is the middle)."
    • addedInput schema / properties / y / description
      Added value: +"Centre down, in % of the frame (18 is near the top; captions sit near 84)."
  2. First observedv0.1.0

TDQS

A4.9/5.0
Behavior5/5

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

Annotations already declare a non-readonly, non-idempotent, non-destructive mutation, so the bar is lower, yet the description still adds undo semantics ("One undo step for the person"), failure behavior (a wrong id is refused with the valid list), and the return payload (shot and text ids) despite there being no output schema.

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

Conciseness5/5

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

Purpose comes first, then parameter meaning, then id provenance, then return value, then the alternative routing. Every sentence carries distinct information despite the density of parentheticals.

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 15-parameter mutation tool with no output schema, the description covers return values, undo impact, error behavior, id sourcing, and sibling routing. Nothing an agent needs in order to call it correctly 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 coverage is 100%, so baseline is 3; the description earns a point by disambiguating preset (the style's text preset: look and font) from action (its animation), a distinction the schema only implies via parenthetical library references. It also reinforces the source constraint on ids, though it adds nothing about timing parameters like at/until, which the schema already handles.

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?

"Add, change or remove on-screen text in a shot" gives a concrete verb set and resource, and the closing sentence explicitly separates it from write_script/assign_line for spoken lines. An agent can tell what this tool owns without opening the schema.

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 a prerequisite (ids must come from the current style, discovered via library) and an explicit exclusion with alternatives (spoken script lines belong to write_script or assign_line). That covers both when-to-use and when-not-to-use.

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