cuttingfloor

Add clip

clip.add

Idempotent

Place media on the timeline. A/V media lands as a linked pair on a video and an audio track. Default: the whole media, after the last clip, overwriting. A picture is scaled to fit the frame (a small logo fills it edge to edge); clip.set_transform {fit: "none"} keeps its own pixel size. Returns the edit result (see the server instructions).

Input Schema

Name	Required	Description	Default
`av`	No	linked: video and audio as a link group; video or audio: only that part	linked
`mode`	No	overwrite replaces what is underneath; insert pushes later clips right	overwrite
`source`	No	Source range in sequence frames, out exclusive. Default: the whole media
`preview`	No	inline: image in the result; link: URI that renders on read; none	link
`at_frame`	No	Where the clip starts. Default: after the last clip
`media_id`	No	Media handle from media.import or a create.* tool
`track_id`	Yes	Track for the clip; a linked A/V clip puts its other half on link_track_id
`timeline_id`	Yes	Timeline handle; every edit returns a new one
`other_tracks`	No	What the other tracks do when this edit moves later clips on the clip's own tracks (linked clips always move with it). stay: they don't move, and the result warns which clips there now play early or late. sync: they get the same change, so titles, overlays and sound stay in step: time taken out here comes out of them too (like range.extract), time added here opens the same gap in them (clips crossing that point are split, as insert does). Locked tracks always stay	stay
`after_clip_id`	No	Start where this clip ends (instead of at_frame)
`link_track_id`	No	Track for the other half of a linked clip. Default: the first track of that kind
`duration_frames`	No	Length for stills (default 5 s); ignored when source is given
`nested_timeline_id`	No	Instead of media: nest another timeline as one clip (a compound clip)

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.

Changed1 schema field changedNov 1, 2026

changedInput schema / properties / source / anyOf

Previous value: -[
-  {
-    "properties": {
-      "in": {
-        "minimum": 0,
-        "type": "integer"
-      },
-      "out": {
-        "minimum": 0,
-        "type": "integer"
-      }
-    },
-    "required": [
-      "in",
-      "out"
-    ],
-    "type": "object"
-  },
-  {
-    "description": "Transcript words i to j (inclusive), from media.get include transcript",
-    "properties": {
-      "words": {
-        "items": false,
-        "maxItems": 2,
-        "minItems": 2,
-        "prefixItems": [
-          {
-            "minimum": 0,
-            "type": "integer"
-          },
-          {
-            "minimum": 0,
-            "type": "integer"
-          }
-        ],
-        "type": "array"
-      }
-    },
-    "required": [
-      "words"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "properties": {
+      "in": {
+        "minimum": 0,
+        "type": "integer"
+      },
+      "out": {
+        "minimum": 0,
+        "type": "integer"
+      }
+    },
+    "required": [
+      "in",
+      "out"
+    ],
+    "type": "object"
+  },
+  {
+    "description": "Transcript words i to j (inclusive), from media.get include transcript: from the frame word i starts in to the frame after word j ends, with no padding (clip.trim adds room for a breath or a word's tail)",
+    "properties": {
+      "words": {
+        "items": false,
+        "maxItems": 2,
+        "minItems": 2,
+        "prefixItems": [
+          {
+            "minimum": 0,
+            "type": "integer"
+          },
+          {
+            "minimum": 0,
+            "type": "integer"
+          }
+        ],
+        "type": "array"
+      }
+    },
+    "required": [
+      "words"
+    ],
+    "type": "object"
+  }
+]

First observedOct 25, 2026

TDQS

A4.4/5.0

Behavior5/5

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

Annotations only declare the safety profile (not read-only, idempotent, non-destructive); the description adds real behaviour: A/V media becomes a linked pair split across video and audio tracks, default placement is after the last clip, and the default mode overwrites. It also discloses the picture auto-fit side effect, which is otherwise invisible and surprising.

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?

Four short sentences, front-loaded with the action and the default behaviour, then the picture-scaling caveat and the return pointer. Each sentence contributes: placement, link semantics, defaults, fit exception, return value.

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 13 parameters, 100% schema coverage, annotations and an output schema, the description covers the parts an agent most needs before calling (placement default, link behaviour, overwrite default) and defers return-value detail to the server instructions. It does not mention the preview or other_tracks semantics, but those are fully handled by the schema.

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

Parameters3/5

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

Schema description coverage is 100%, so all 13 parameters (including other_tracks, mode, av, source, preview) are already documented in the schema. The description only echoes a few defaults (whole media source, placement after last clip) and adds no syntax or interaction detail beyond what the schema provides — baseline 3 applies.

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?

Opens with a specific verb+resource ("Place media on the timeline") and immediately specifies the two placement modes that distinguish it: linked A/V pair creation and default overwrite-after-last-clip. An agent can tell this apart from clip.replace, clip.move or clip.trim 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 Guidelines4/5

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

Gives concrete defaults (whole media, after the last clip, overwriting) that tell an agent what happens when it omits arguments, plus one explicit redirect: use clip.set_transform {fit: "none"} if a picture should keep its pixel size. No exclusion against siblings like clip.replace for swapping existing clips, so not a full 5.

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.