Skip to main content
Glama
Sign In

cuttingfloor

by io.github.Mvp2o-ai
OverviewDiscussionsAdmin

Set mask

clip.set_mask
Idempotent

Select part of a video clip, then show, hide or fill it: rectangle (rounded), ellipse, linear, mirror, heart, star, polygon or matte (a media's alpha, e.g. a create.cutout), with feather and invert. Several shapes: add. A fill paints the selection from the picture around it and from earlier frames where that area showed, so something that never moves against its background leaves a smudge: nothing ever shows what is behind it. It is a job of its own (job.list shows its progress); a render that needs it names the job until it is done, and an export waits for it. Position, size and rotation animate like transform values. Coordinates are fractions of the clip's fitted frame: a sequence-shaped box with the picture fitted inside (bars where the shapes differ), before the clip's scale and position. A narrower picture fills k = (its aspect / the sequence's) of the box width, centred, so a picture-fraction box maps to x = 0.5 + (x - 0.5) * k, width * k (a wider picture: the same on y and height, with k = the sequence aspect / its). null removes the mask. Returns the edit result (see the server instructions).

Input Schema

NameRequiredDescriptionDefault
maskYesnull removes the mask
clip_idYes
previewNoinline: image in the result; link: URI that renders on read; nonelink
timeline_idYesTimeline handle; every edit returns a new one

Output Schema

NameRequiredDescriptionDefault
parentYesTimeline handle; every edit returns a new one
changedYes
clip_idNo
previewYes
clip_idsNo
track_idNo
warningsYes
placementsNoWhere each clip the edit moved, cropped, masked or animated shows, sequence pixels
timeline_idYesTimeline handle; every edit returns a new one

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / mask / anyOf
      Previous value: -[
-  {
-    "properties": {
-      "add": {
-        "description": "More shapes in the same selection, e.g. two panels; feather, invert and mode apply to all",
-        "items": {
-          "$ref": "#/$defs/MaskShape"
-        },
-        "maxItems": 8,
-        "minItems": 1,
-        "type": "array"
-      },
-      "corner_radius": {
-        "description": "rectangle: corner radius as a fraction of its short side",
-        "maximum": 0.5,
-        "minimum": 0,
-        "type": "number"
-      },
-      "feather": {
-        "description": "Soft edge as a fraction of the picture short side",
-        "maximum": 0.5,
-        "minimum": 0,
-        "type": "number"
-      },
-      "height": {
-        "$ref": "#/$defs/Animatable",
-        "description": "Fraction of the fitted frame height (default 0.5); band thickness for mirror; 0 to 10"
-      },
-      "invert": {
-        "description": "Select the outside instead",
-        "type": "boolean"
-      },
-      "media_id": {
-        "description": "matte: media whose alpha (or brightness) selects",
-        "pattern": "^m_[0-9a-z]{26}$",
-        "type": "string"
-      },
-      "mode": {
-        "description": "show (default) only the selection, hide it, or fill it: painted in from its surroundings",
-        "enum": [
-          "show",
-          "hide",
-          "fill"
-        ],
-        "type": "string"
-      },
-      "points": {
-        "anyOf": [
-          {
-            "$ref": "#/$defs/MaskPoints"
-          },
-          {
-            "properties": {
-              "keyframes": {
-                "items": {
-                  "properties": {
-                    "ease": {
-                      "type": "string"
-                    },
-                    "frame": {
-                      "maximum": 100000000,
-                      "minimum": -1000000,
-                      "type": "integer"
-                    },
-                    "points": {
-                      "$ref": "#/$defs/MaskPoints"
-                    }
-                  },
-                  "required": [
-                    "frame",
-                    "points"
-                  ],
-                  "type": "object"
-                },
-                "maxItems": 1000,
-                "minItems": 1,
-                "type": "array"
-              }
-            },
-            "required": [
-              "keyframes"
-            ],
-            "type": "object"
-          }
-        ],
-        "description": "polygon: [x, y] corners in the fitted frame, 0–1, or {keyframes: [{frame, points, ease}]}"
-      },
-      "rotation": {
-        "$ref": "#/$defs/Animatable",
-        "description": "Degrees clockwise; for linear, the edge angle; -36000 to 36000"
-      },
-      "shape": {
-        "enum": [
-          "rectangle",
-          "ellipse",
-          "linear",
-          "mirror",
-          "heart",
-          "star",
-          "polygon",
-          "matte"
-        ],
-        "type": "string"
-      },
-      "width": {
-        "$ref": "#/$defs/Animatable",
-        "description": "Fraction of the fitted frame width (default 0.5); 0 to 10"
-      },
-      "x": {
-        "$ref": "#/$defs/Animatable",
-        "description": "Mask centre x in the fitted frame, 0–1 (default 0.5); -4 to 5"
-      },
-      "y": {
-        "$ref": "#/$defs/Animatable",
-        "description": "Mask centre y in the fitted frame, 0–1 (default 0.5); -4 to 5"
-      }
-    },
-    "required": [
-      "shape"
-    ],
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "properties": {
+      "add": {
+        "description": "More shapes in the same selection, e.g. two panels; feather, invert and mode apply to all",
+        "items": {
+          "$ref": "#/$defs/MaskShape"
+        },
+        "maxItems": 8,
+        "minItems": 1,
+        "type": "array"
+      },
+      "corner_radius": {
+        "description": "rectangle: corner radius as a fraction of its short side",
+        "maximum": 0.5,
+        "minimum": 0,
+        "type": "number"
+      },
+      "feather": {
+        "description": "Soft edge as a fraction of the picture short side",
+        "maximum": 0.5,
+        "minimum": 0,
+        "type": "number"
+      },
+      "height": {
+        "$ref": "#/$defs/Animatable",
+        "description": "Fraction of the fitted frame height (default 0.5); band thickness for mirror; 0 to 10"
+      },
+      "invert": {
+        "description": "Select the outside instead",
+        "type": "boolean"
+      },
+      "media_id": {
+        "description": "matte: media whose alpha (or brightness) selects",
+        "pattern": "^m_[0-9a-z]{26}$",
+        "type": "string"
+      },
+      "mode": {
+        "description": "show (default) only the selection, hide it, or fill it (painted in from around it and from earlier frames)",
+        "enum": [
+          "show",
+          "hide",
+          "fill"
+        ],
+        "type": "string"
+      },
+      "points": {
+        "anyOf": [
+          {
+            "$ref": "#/$defs/MaskPoints"
+          },
+          {
+            "properties": {
+              "keyframes": {
+                "items": {
+                  "properties": {
+                    "ease": {
+                      "type": "string"
+                    },
+                    "frame": {
+                      "maximum": 100000000,
+                      "minimum": -1000000,
+                      "type": "integer"
+                    },
+                    "points": {
+                      "$ref": "#/$defs/MaskPoints"
+                    }
+                  },
+                  "required": [
+                    "frame",
+                    "points"
+                  ],
+                  "type": "object"
+                },
+                "maxItems": 1000,
+                "minItems": 1,
+                "type": "array"
+              }
+            },
+            "required": [
+              "keyframes"
+            ],
+            "type": "object"
+          }
+        ],
+        "description": "polygon: [x, y] corners in the fitted frame, 0–1, or {keyframes: [{frame, points, ease}]}"
+      },
+      "rotation": {
+        "$ref": "#/$defs/Animatable",
+        "description": "Degrees clockwise; for linear, the edge angle; -36000 to 36000"
+      },
+      "shape": {
+        "enum": [
+          "rectangle",
+          "ellipse",
+          "linear",
+          "mirror",
+          "heart",
+          "star",
+          "polygon",
+          "matte"
+        ],
+        "type": "string"
+      },
+      "width": {
+        "$ref": "#/$defs/Animatable",
+        "description": "Fraction of the fitted frame width (default 0.5); 0 to 10"
+      },
+      "x": {
+        "$ref": "#/$defs/Animatable",
+        "description": "Mask centre x in the fitted frame, 0–1 (default 0.5); -4 to 5"
+      },
+      "y": {
+        "$ref": "#/$defs/Animatable",
+        "description": "Mask centre y in the fitted frame, 0–1 (default 0.5); -4 to 5"
+      }
+    },
+    "required": [
+      "shape"
+    ],
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]
  2. Changed2 schema fields changed
    • addedInput schema / $defs / MaskShape
      Added value: +{
+  "properties": {
+    "corner_radius": {
+      "description": "rectangle: corner radius as a fraction of its short side",
+      "maximum": 0.5,
+      "minimum": 0,
+      "type": "number"
+    },
+    "height": {
+      "$ref": "#/$defs/Animatable",
+      "description": "Fraction of the fitted frame height (default 0.5); band thickness for mirror; 0 to 10"
+    },
+    "media_id": {
+      "description": "matte: media whose alpha (or brightness) selects",
+      "pattern": "^m_[0-9a-z]{26}$",
+      "type": "string"
+    },
+    "points": {
+      "anyOf": [
+        {
+          "$ref": "#/$defs/MaskPoints"
+        },
+        {
+          "properties": {
+            "keyframes": {
+              "items": {
+                "properties": {
+                  "ease": {
+                    "type": "string"
+                  },
+                  "frame": {
+                    "maximum": 100000000,
+                    "minimum": -1000000,
+                    "type": "integer"
+                  },
+                  "points": {
+                    "$ref": "#/$defs/MaskPoints"
+                  }
+                },
+                "required": [
+                  "frame",
+                  "points"
+                ],
+                "type": "object"
+              },
+              "maxItems": 1000,
+              "minItems": 1,
+              "type": "array"
+            }
+          },
+          "required": [
+            "keyframes"
+          ],
+          "type": "object"
+        }
+      ],
+      "description": "polygon: [x, y] corners in the fitted frame, 0–1, or {keyframes: [{frame, points, ease}]}"
+    },
+    "rotation": {
+      "$ref": "#/$defs/Animatable",
+      "description": "Degrees clockwise; for linear, the edge angle; -36000 to 36000"
+    },
+    "shape": {
+      "enum": [
+        "rectangle",
+        "ellipse",
+        "linear",
+        "mirror",
+        "heart",
+        "star",
+        "polygon",
+        "matte"
+      ],
+      "type": "string"
+    },
+    "width": {
+      "$ref": "#/$defs/Animatable",
+      "description": "Fraction of the fitted frame width (default 0.5); 0 to 10"
+    },
+    "x": {
+      "$ref": "#/$defs/Animatable",
+      "description": "Mask centre x in the fitted frame, 0–1 (default 0.5); -4 to 5"
+    },
+    "y": {
+      "$ref": "#/$defs/Animatable",
+      "description": "Mask centre y in the fitted frame, 0–1 (default 0.5); -4 to 5"
+    }
+  },
+  "required": [
+    "shape"
+  ],
+  "type": "object"
+}
    • changedInput schema / properties / mask / anyOf
      Previous value: -[
-  {
-    "properties": {
-      "corner_radius": {
-        "description": "rectangle: corner radius as a fraction of its short side",
-        "maximum": 0.5,
-        "minimum": 0,
-        "type": "number"
-      },
-      "feather": {
-        "description": "Soft edge as a fraction of the picture short side",
-        "maximum": 0.5,
-        "minimum": 0,
-        "type": "number"
-      },
-      "height": {
-        "$ref": "#/$defs/Animatable",
-        "description": "Fraction of the fitted frame height (default 0.5); band thickness for mirror; 0 to 10"
-      },
-      "invert": {
-        "description": "Select the outside instead",
-        "type": "boolean"
-      },
-      "media_id": {
-        "description": "matte: media whose alpha (or brightness) selects",
-        "pattern": "^m_[0-9a-z]{26}$",
-        "type": "string"
-      },
-      "mode": {
-        "description": "show (default) only the selection, hide it, or fill it from its surroundings",
-        "enum": [
-          "show",
-          "hide",
-          "fill"
-        ],
-        "type": "string"
-      },
-      "points": {
-        "anyOf": [
-          {
-            "$ref": "#/$defs/MaskPoints"
-          },
-          {
-            "properties": {
-              "keyframes": {
-                "items": {
-                  "properties": {
-                    "ease": {
-                      "type": "string"
-                    },
-                    "frame": {
-                      "maximum": 100000000,
-                      "minimum": -1000000,
-                      "type": "integer"
-                    },
-                    "points": {
-                      "$ref": "#/$defs/MaskPoints"
-                    }
-                  },
-                  "required": [
-                    "frame",
-                    "points"
-                  ],
-                  "type": "object"
-                },
-                "maxItems": 1000,
-                "minItems": 1,
-                "type": "array"
-              }
-            },
-            "required": [
-              "keyframes"
-            ],
-            "type": "object"
-          }
-        ],
-        "description": "polygon: [x, y] corners in the fitted frame, 0–1, or {keyframes: [{frame, points, ease}]}"
-      },
-      "rotation": {
-        "$ref": "#/$defs/Animatable",
-        "description": "Degrees clockwise; for linear, the edge angle; -36000 to 36000"
-      },
-      "shape": {
-        "enum": [
-          "rectangle",
-          "ellipse",
-          "linear",
-          "mirror",
-          "heart",
-          "star",
-          "polygon",
-          "matte"
-        ],
-        "type": "string"
-      },
-      "width": {
-        "$ref": "#/$defs/Animatable",
-        "description": "Fraction of the fitted frame width (default 0.5); 0 to 10"
-      },
-      "x": {
-        "$ref": "#/$defs/Animatable",
-        "description": "Mask centre x in the fitted frame, 0–1 (default 0.5); -4 to 5"
-      },
-      "y": {
-        "$ref": "#/$defs/Animatable",
-        "description": "Mask centre y in the fitted frame, 0–1 (default 0.5); -4 to 5"
-      }
-    },
-    "required": [
-      "shape"
-    ],
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "properties": {
+      "add": {
+        "description": "More shapes in the same selection, e.g. two panels; feather, invert and mode apply to all",
+        "items": {
+          "$ref": "#/$defs/MaskShape"
+        },
+        "maxItems": 8,
+        "minItems": 1,
+        "type": "array"
+      },
+      "corner_radius": {
+        "description": "rectangle: corner radius as a fraction of its short side",
+        "maximum": 0.5,
+        "minimum": 0,
+        "type": "number"
+      },
+      "feather": {
+        "description": "Soft edge as a fraction of the picture short side",
+        "maximum": 0.5,
+        "minimum": 0,
+        "type": "number"
+      },
+      "height": {
+        "$ref": "#/$defs/Animatable",
+        "description": "Fraction of the fitted frame height (default 0.5); band thickness for mirror; 0 to 10"
+      },
+      "invert": {
+        "description": "Select the outside instead",
+        "type": "boolean"
+      },
+      "media_id": {
+        "description": "matte: media whose alpha (or brightness) selects",
+        "pattern": "^m_[0-9a-z]{26}$",
+        "type": "string"
+      },
+      "mode": {
+        "description": "show (default) only the selection, hide it, or fill it: painted in from its surroundings",
+        "enum": [
+          "show",
+          "hide",
+          "fill"
+        ],
+        "type": "string"
+      },
+      "points": {
+        "anyOf": [
+          {
+            "$ref": "#/$defs/MaskPoints"
+          },
+          {
+            "properties": {
+              "keyframes": {
+                "items": {
+                  "properties": {
+                    "ease": {
+                      "type": "string"
+                    },
+                    "frame": {
+                      "maximum": 100000000,
+                      "minimum": -1000000,
+                      "type": "integer"
+                    },
+                    "points": {
+                      "$ref": "#/$defs/MaskPoints"
+                    }
+                  },
+                  "required": [
+                    "frame",
+                    "points"
+                  ],
+                  "type": "object"
+                },
+                "maxItems": 1000,
+                "minItems": 1,
+                "type": "array"
+              }
+            },
+            "required": [
+              "keyframes"
+            ],
+            "type": "object"
+          }
+        ],
+        "description": "polygon: [x, y] corners in the fitted frame, 0–1, or {keyframes: [{frame, points, ease}]}"
+      },
+      "rotation": {
+        "$ref": "#/$defs/Animatable",
+        "description": "Degrees clockwise; for linear, the edge angle; -36000 to 36000"
+      },
+      "shape": {
+        "enum": [
+          "rectangle",
+          "ellipse",
+          "linear",
+          "mirror",
+          "heart",
+          "star",
+          "polygon",
+          "matte"
+        ],
+        "type": "string"
+      },
+      "width": {
+        "$ref": "#/$defs/Animatable",
+        "description": "Fraction of the fitted frame width (default 0.5); 0 to 10"
+      },
+      "x": {
+        "$ref": "#/$defs/Animatable",
+        "description": "Mask centre x in the fitted frame, 0–1 (default 0.5); -4 to 5"
+      },
+      "y": {
+        "$ref": "#/$defs/Animatable",
+        "description": "Mask centre y in the fitted frame, 0–1 (default 0.5); -4 to 5"
+      }
+    },
+    "required": [
+      "shape"
+    ],
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]
  3. Changed4 schema fields changed
    • changedInput schema / $defs / Animatable / anyOf
      Previous value: -[
-  {
-    "type": "number"
-  },
-  {
-    "properties": {
-      "keyframes": {
-        "description": "frame is relative to the clip start; ease from video://catalog/eases",
-        "items": {
-          "properties": {
-            "ease": {
-              "type": "string"
-            },
-            "frame": {
-              "maximum": 100000000,
-              "minimum": -1000000,
-              "type": "integer"
-            },
-            "value": {
-              "type": "number"
-            }
-          },
-          "required": [
-            "frame",
-            "value"
-          ],
-          "type": "object"
-        },
-        "maxItems": 1000,
-        "minItems": 1,
-        "type": "array"
-      }
-    },
-    "required": [
-      "keyframes"
-    ],
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "type": "number"
+  },
+  {
+    "properties": {
+      "keyframes": {
+        "description": "frame is from the clip start; ease shapes the move from this keyframe to the next (default linear; hold waits, then jumps)",
+        "items": {
+          "properties": {
+            "ease": {
+              "enum": [
+                "linear",
+                "hold",
+                "smooth",
+                "sine_in",
+                "sine_out",
+                "sine_in_out",
+                "quad_in",
+                "quad_out",
+                "quad_in_out",
+                "cubic_in",
+                "cubic_out",
+                "cubic_in_out",
+                "quart_in",
+                "quart_out",
+                "quart_in_out",
+                "quint_in",
+                "quint_out",
+                "quint_in_out",
+                "expo_in",
+                "expo_out",
+                "expo_in_out",
+                "circ_in",
+                "circ_out",
+                "circ_in_out",
+                "back_in",
+                "back_out",
+                "back_in_out",
+                "elastic_in",
+                "elastic_out",
+                "elastic_in_out",
+                "bounce_in",
+                "bounce_out",
+                "bounce_in_out"
+              ],
+              "type": "string"
+            },
+            "frame": {
+              "maximum": 100000000,
+              "minimum": -1000000,
+              "type": "integer"
+            },
+            "value": {
+              "type": "number"
+            }
+          },
+          "required": [
+            "frame",
+            "value"
+          ],
+          "type": "object"
+        },
+        "maxItems": 1000,
+        "minItems": 1,
+        "type": "array"
+      }
+    },
+    "required": [
+      "keyframes"
+    ],
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]
    • addedInput schema / $defs / MaskPoints
      Added value: +{
+  "items": {
+    "items": false,
+    "maxItems": 2,
+    "minItems": 2,
+    "prefixItems": [
+      {
+        "maximum": 5,
+        "minimum": -4,
+        "type": "number"
+      },
+      {
+        "maximum": 5,
+        "minimum": -4,
+        "type": "number"
+      }
+    ],
+    "type": "array"
+  },
+  "maxItems": 64,
+  "minItems": 3,
+  "type": "array"
+}
    • changedInput schema / properties / mask / anyOf
      Previous value: -[
-  {
-    "properties": {
-      "corner_radius": {
-        "description": "rectangle: corner radius as a fraction of its short side",
-        "maximum": 0.5,
-        "minimum": 0,
-        "type": "number"
-      },
-      "feather": {
-        "description": "Soft edge as a fraction of the picture short side",
-        "maximum": 0.5,
-        "minimum": 0,
-        "type": "number"
-      },
-      "height": {
-        "$ref": "#/$defs/Animatable",
-        "description": "Fraction of the picture height (default 0.5); band thickness for mirror; 0 to 10"
-      },
-      "invert": {
-        "description": "Keep the outside instead",
-        "type": "boolean"
-      },
-      "points": {
-        "description": "polygon: [x, y] corners in the clip picture, 0–1",
-        "items": {
-          "items": false,
-          "maxItems": 2,
-          "minItems": 2,
-          "prefixItems": [
-            {
-              "maximum": 5,
-              "minimum": -4,
-              "type": "number"
-            },
-            {
-              "maximum": 5,
-              "minimum": -4,
-              "type": "number"
-            }
-          ],
-          "type": "array"
-        },
-        "maxItems": 64,
-        "minItems": 3,
-        "type": "array"
-      },
-      "rotation": {
-        "$ref": "#/$defs/Animatable",
-        "description": "Degrees clockwise; for linear, the edge angle; -36000 to 36000"
-      },
-      "shape": {
-        "enum": [
-          "rectangle",
-          "ellipse",
-          "linear",
-          "mirror",
-          "heart",
-          "star",
-          "polygon"
-        ],
-        "type": "string"
-      },
-      "width": {
-        "$ref": "#/$defs/Animatable",
-        "description": "Fraction of the picture width (default 0.5); 0 to 10"
-      },
-      "x": {
-        "$ref": "#/$defs/Animatable",
-        "description": "Mask centre x in the clip picture, 0–1 (default 0.5); -4 to 5"
-      },
-      "y": {
-        "$ref": "#/$defs/Animatable",
-        "description": "Mask centre y in the clip picture, 0–1 (default 0.5); -4 to 5"
-      }
-    },
-    "required": [
-      "shape"
-    ],
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "properties": {
+      "corner_radius": {
+        "description": "rectangle: corner radius as a fraction of its short side",
+        "maximum": 0.5,
+        "minimum": 0,
+        "type": "number"
+      },
+      "feather": {
+        "description": "Soft edge as a fraction of the picture short side",
+        "maximum": 0.5,
+        "minimum": 0,
+        "type": "number"
+      },
+      "height": {
+        "$ref": "#/$defs/Animatable",
+        "description": "Fraction of the fitted frame height (default 0.5); band thickness for mirror; 0 to 10"
+      },
+      "invert": {
+        "description": "Select the outside instead",
+        "type": "boolean"
+      },
+      "media_id": {
+        "description": "matte: media whose alpha (or brightness) selects",
+        "pattern": "^m_[0-9a-z]{26}$",
+        "type": "string"
+      },
+      "mode": {
+        "description": "show (default) only the selection, hide it, or fill it from its surroundings",
+        "enum": [
+          "show",
+          "hide",
+          "fill"
+        ],
+        "type": "string"
+      },
+      "points": {
+        "anyOf": [
+          {
+            "$ref": "#/$defs/MaskPoints"
+          },
+          {
+            "properties": {
+              "keyframes": {
+                "items": {
+                  "properties": {
+                    "ease": {
+                      "type": "string"
+                    },
+                    "frame": {
+                      "maximum": 100000000,
+                      "minimum": -1000000,
+                      "type": "integer"
+                    },
+                    "points": {
+                      "$ref": "#/$defs/MaskPoints"
+                    }
+                  },
+                  "required": [
+                    "frame",
+                    "points"
+                  ],
+                  "type": "object"
+                },
+                "maxItems": 1000,
+                "minItems": 1,
+                "type": "array"
+              }
+            },
+            "required": [
+              "keyframes"
+            ],
+            "type": "object"
+          }
+        ],
+        "description": "polygon: [x, y] corners in the fitted frame, 0–1, or {keyframes: [{frame, points, ease}]}"
+      },
+      "rotation": {
+        "$ref": "#/$defs/Animatable",
+        "description": "Degrees clockwise; for linear, the edge angle; -36000 to 36000"
+      },
+      "shape": {
+        "enum": [
+          "rectangle",
+          "ellipse",
+          "linear",
+          "mirror",
+          "heart",
+          "star",
+          "polygon",
+          "matte"
+        ],
+        "type": "string"
+      },
+      "width": {
+        "$ref": "#/$defs/Animatable",
+        "description": "Fraction of the fitted frame width (default 0.5); 0 to 10"
+      },
+      "x": {
+        "$ref": "#/$defs/Animatable",
+        "description": "Mask centre x in the fitted frame, 0–1 (default 0.5); -4 to 5"
+      },
+      "y": {
+        "$ref": "#/$defs/Animatable",
+        "description": "Mask centre y in the fitted frame, 0–1 (default 0.5); -4 to 5"
+      }
+    },
+    "required": [
+      "shape"
+    ],
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]
    • addedOutput schema / properties / placements
      Added value: +{
+  "description": "Where each clip the edit moved, cropped, masked or animated shows, sequence pixels",
+  "items": {
+    "properties": {
+      "clip_id": {
+        "type": "string"
+      },
+      "complete": {
+        "description": "true: values move in straight lines between entries; false: evenly sampled",
+        "type": "boolean"
+      },
+      "frames": {
+        "items": {
+          "properties": {
+            "frame": {
+              "description": "From the clip start",
+              "type": "number"
+            },
+            "opacity": {
+              "type": "number"
+            },
+            "picture": {
+              "description": "The whole picture, before crop and mask and rotation",
+              "properties": {
+                "h": {
+                  "type": "number"
+                },
+                "w": {
+                  "type": "number"
+                },
+                "x": {
+                  "type": "number"
+                },
+                "y": {
+                  "type": "number"
+                }
+              },
+              "required": [
+                "x",
+                "y",
+                "w",
+                "h"
+              ],
+              "type": "object"
+            },
+            "rotation": {
+              "type": "number"
+            },
+            "source": {
+              "anyOf": [
+                {
+                  "properties": {
+                    "h": {
+                      "type": "number"
+                    },
+                    "w": {
+                      "type": "number"
+                    },
+                    "x": {
+                      "type": "number"
+                    },
+                    "y": {
+                      "type": "number"
+                    }
+                  },
+                  "required": [
+                    "x",
+                    "y",
+                    "w",
+                    "h"
+                  ],
+                  "type": "object"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "The part of the source that shows, source pixels"
+            },
+            "visible": {
+              "anyOf": [
+                {
+                  "properties": {
+                    "h": {
+                      "type": "number"
+                    },
+                    "w": {
+                      "type": "number"
+                    },
+                    "x": {
+                      "type": "number"
+                    },
+                    "y": {
+                      "type": "number"
+                    }
+                  },
+                  "required": [
+                    "x",
+                    "y",
+                    "w",
+                    "h"
+                  ],
+                  "type": "object"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "What it shows: crop and mask applied, rotated, inside the frame; null: nothing"
+            }
+          },
+          "required": [
+            "frame",
+            "picture",
+            "rotation",
+            "opacity",
+            "visible",
+            "source"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      }
+    },
+    "required": [
+      "clip_id",
+      "frames",
+      "complete"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}
  4. First observed

TDQS

A4.5/5.0
Behavior5/5

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

Goes well beyond the annotations (which only say idempotent/non-destructive): it discloses that the operation runs as its own asynchronous job, that job.list tracks progress, that dependent renders name the job, and that exports wait on it. It also warns about the fill smudge limitation — genuinely non-obvious behavior an agent could not infer elsewhere.

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 core action and shape list before the denser coordinate and job details. It is long and somewhat run-on in places, but nearly every sentence carries substantive information; trimming is possible but little is truly wasted.

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?

Given an output schema exists, return values need not be explained (it still references 'the edit result'), and the async job, coordinate, and fill behaviors are all covered. A brief note on required permissions or default-mode implications would round it out, but the definition is complete enough to invoke correctly.

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 75%, so the schema already documents most parameters; the description adds real value by explaining the fitted-frame coordinate model and the k = aspect-ratio mapping formula, which clarifies how 0–1 coordinates behave on non-matching aspect ratios. It does not cover every param (e.g. preview, timeline_id), but the hard-to-grok spatial semantics are covered.

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 and resource ('Select part of a video clip, then show, hide or fill it') and enumerates the exact shape vocabulary, which lets an agent distinguish it from sibling tools like clip.set_transform or create.matte without opening a 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?

Clear about operational context: multiple shapes go through 'add', a fill vs show/hide distinction is explained, and 'null removes the mask' signals the removal path. It stops short of naming an alternative tool for related tasks (e.g. when to use create.matte vs a matte mask), so no explicit sibling routing.

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

All cuttingfloor toolsInspect
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.

Resources