Skip to main content
Glama

Add a graphic to a long video

add_graphic

Adds a motion graphic to a long-form project, pinned to the transcript: it starts as the word at is said and ends with until (default its build plus 2 s). Checks the data against the template and, with check_against, every figure against the scene's script, before saving; then starts its render. Returns graphic_id, status (rendering, ready, failed with the error, or hidden with the reason), task_id for get_task, start_seconds and end_seconds in the finished video, and what to do next. Costs 1 credit per started 2 s of the graphic (3 full frame).

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "project_id": "<project_id>",
      "template": "<template>",
      "data": "<data>",
      "at": "<at>"
    },
    "name": "add_graphic"
  }
}

Input Schema

NameRequiredDescriptionDefault
atYesThe word it starts on, as { take_id, word } with the word's index from get_transcript
dataYesThe template's data, matching its data_schema in list_graphics
beatsNoOne word per step (a worked sum's lines or a timeline's markers), in order: each step appears as its word is said. null for the template's own timing
untilNoThe word it ends on; null for its build plus 2 s, at least 5 s (30 s at most)
templateYesA template from list_graphics
placementNofull replaces the picture; right, left and band are overlays. Default the template's first (list_graphics lists them)
project_idYesFrom create_project
check_againstNoA scene id (its script, else its take's transcript) or the script's text: every figure in the data must appear in it

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A3.9/5.0
Behavior4/5

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses real behavior: the graphic is pinned to transcript words, the default duration is build plus 2 s clamped to 5–30 s, validation runs before saving, and a render is kicked off automatically. It also states the cost model (1 credit per started 2 s, 3 for full frame) and enumerates return fields including failure and hidden states. It stops short of describing permissions or whether a failed render can be retried cheaply.

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?

Everything is front-loaded: verb and pinning mechanism first, then validation, then return values, then cost. The prose is dense and semicolon-heavy, and the return-value enumeration could be tightened, but no sentence is filler.

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?

With no output schema, the description carries the return contract itself and does so explicitly (graphic_id, status variants, task_id, start_seconds/end_seconds). For an 8-parameter tool with nested objects and enum placement, the combination of schema documentation plus the description's timing, cost, and status semantics leaves nothing an agent needs missing before calling it.

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 already 100%, but the description still adds meaning the schema does not: 'at' is framed as the word where the graphic starts and 'until' as where it ends, with the default duration rule and the 5–30 s bounds restated in prose, and check_against is explained as 'every figure against the scene's script'. That is genuine semantic enrichment on top of an already-documented 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?

The description opens with a specific verb and resource ('Adds a motion graphic to a long-form project') and immediately names the distinguishing mechanism ('pinned to the transcript'). It is clearly a create/mutation operation rather than a preview or update, but it never names the adjacent siblings (preview_graphic, update_graphic) that an agent would weigh it against.

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

Usage Guidelines3/5

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

Usage is implied rather than stated: it explains that validation happens before saving and that check_against can verify figures against a scene's script, which hints at when to supply that parameter. There is no explicit when-to-use/when-not guidance, no mention of previewing first, and no routing to alternatives for existing graphics.

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.

Resources