cuttingfloor

Add captions

caption.add

Idempotent

Captions on a video track from segments (with optional word timings for highlights), from SRT/VTT text, or in_clip: segments timed in seconds of a clip's media, such as transcript word times, placed where they play. One clip per caption; returns their clip_ids. A style field you leave out takes the published default (video://catalog/text: bold white Inter at 6% of the frame height, near the bottom, with a black outline); timeline.get shows the full style. Lines wrap on their own at style max_width (a fraction of the frame width), balanced in length; \n forces a break. style max_lines caps the lines on screen at once: a longer caption shows a screenful at a time, each from its first word's time. A segment's spans style part of its text (words first_word to last_word, from 0: the timed words, or the text split at spaces), e.g. the key word in yellow. Burned in when exported. Returns the edit result (see the server instructions).

Input Schema

Name	Required	Description	Default
`srt`	No	SubRip text instead of segments
`vtt`	No	WebVTT text instead of segments
`style`	No
`in_clip`	No	Segments timed in seconds of a clip's media (e.g. transcript word times), placed where those moments play in the clip, through speed changes; what doesn't play is left out
`preview`	No	inline: image in the result; link: URI that renders on read; none	link
`segments`	No
`track_id`	Yes	A video track for the captions, usually the top one
`timeline_id`	Yes	Timeline handle; every edit returns a new one
`offset_frames`	No	Shifts srt/vtt times

Output Schema

Name	Required	Description
`parent`	Yes	Timeline handle; every edit returns a new one
`changed`	Yes
`clip_id`	No
`preview`	Yes
`clip_ids`	No
`track_id`	No
`warnings`	Yes
`timeline_id`	Yes	Timeline handle; every edit returns a new one

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 schema fields changedNov 1, 2026

addedInput schema / $defs / TextSpan

Added value: +{
+  "properties": {
+    "bold": {
+      "type": "boolean"
+    },
+    "color": {
+      "type": "string"
+    },
+    "first_word": {
+      "maximum": 10000,
+      "minimum": 0,
+      "type": "integer"
+    },
+    "italic": {
+      "type": "boolean"
+    },
+    "last_word": {
+      "maximum": 10000,
+      "minimum": 0,
+      "type": "integer"
+    },
+    "size": {
+      "description": "Of frame height",
+      "maximum": 1,
+      "minimum": 0.005,
+      "type": "number"
+    },
+    "underline": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "first_word",
+    "last_word"
+  ],
+  "type": "object"
+}

changedInput schema / $defs / TextStyle / properties / highlight / anyOf

Previous value: -[
-  {
-    "properties": {
-      "color": {
-        "type": "string"
-      },
-      "mode": {
-        "enum": [
-          "none",
-          "fill",
-          "word",
-          "karaoke",
-          "pop"
-        ],
-        "type": "string"
-      }
-    },
-    "required": [
-      "mode",
-      "color"
-    ],
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "properties": {
+      "color": {
+        "type": "string"
+      },
+      "mode": {
+        "description": "Needs caption word timings. karaoke: each word takes color as it is spoken and keeps it; fill: likewise, sweeping across each word; word: only the word being spoken; pop: that word, growing a little",
+        "enum": [
+          "none",
+          "fill",
+          "word",
+          "karaoke",
+          "pop"
+        ],
+        "type": "string"
+      }
+    },
+    "required": [
+      "mode",
+      "color"
+    ],
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

addedInput schema / $defs / TextStyle / properties / max_lines

Added value: +{
+  "anyOf": [
+    {
+      "maximum": 20,
+      "minimum": 1,
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "At most this many lines at once: longer text shows in turn, a screenful at a time, each from its first word (by word timing, or by length without it). Lines are broken here, by the font, balanced in length; null shows it all at once"
+}

addedInput schema / $defs / TextStyle / properties / max_width / description

Added value: +"Of frame width: longer text wraps onto more lines, balanced in length"

addedInput schema / properties / in_clip / properties / segments / items / properties / spans

Added value: +{
+  "description": "Style part of the text: each span restyles words first_word to last_word (from 0: the timed words, or the text split at spaces), e.g. one word in yellow",
+  "items": {
+    "$ref": "#/$defs/TextSpan"
+  },
+  "maxItems": 500,
+  "type": "array"
+}

addedInput schema / properties / segments / items / properties / spans

Added value: +{
+  "description": "Style part of the text: each span restyles words first_word to last_word (from 0: the timed words, or the text split at spaces), e.g. one word in yellow",
+  "items": {
+    "$ref": "#/$defs/TextSpan"
+  },
+  "maxItems": 500,
+  "type": "array"
+}

First observedOct 25, 2026

TDQS

A4.2/5.0

Behavior5/5

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

Goes well past the annotations: it discloses the exact default style when a style field is omitted, that captions are burned in at export, that lines wrap at max_width and balance in length, that max_lines shows a screenful at a time from each caption's first word, and that \n forces a break. It also notes clip_ids are returned. One soft caution: annotations claim idempotentHint=true while the text describes creating clips and returning new ids, which an agent may read as additive, but the description does not explicitly assert repeated calls duplicate, so this is not a hard contradiction.

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?

Front-loads the input modes, which is the right ordering, and every clause carries information. It is, however, one dense paragraph with heavy parenthetical nesting, so style behavior (defaults, wrapping, spans) blurs into the input-mode explanation rather than being separated.

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?

With an output schema present, the 'Returns the edit result (see the server instructions)' pointer is sufficient and the burn-in-on-export note covers the non-obvious side effect. Coverage of the style subsystem is thorough for a 9-parameter nested schema; only preview and offset_frames go unmentioned, and both are documented in the schema.

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 78%, so the baseline would be 3, but the description adds real semantics: what in_clip timing means ('placed where those moments play ... through speed changes; what doesn't play is left out'), how spans index words ('the timed words, or the text split at spaces'), and how max_width/max_lines interact with wrapping. It leaves offset_frames and preview entirely to the 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?

States a specific resource (captions) and the three input forms (segments with word timings, srt/vtt text, in_clip media-timed segments), plus the effect (one clip per caption, burned in on export). An agent can tell this is the captioning tool rather than a generic text operation, though it never names the nearest siblings (text.set, title.add) to draw the boundary explicitly.

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?

The three input modes are each given a selecting condition: 'segments (with optional word timings for highlights)', 'from SRT/VTT text', and 'in_clip: segments timed in seconds of a clip's media, such as transcript word times'. It also points to timeline.get when the caller needs the full style. No explicit exclusions against text.set/title.add, which keeps it out of 5 territory.

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

All cuttingfloor tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.