Skip to main content
Glama
Sign In
WeftCut

WeftCut

by WeftCut
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

set_keyframe

Idempotent

Insert or update a keyframe on a layer parameter at a given timeline time. Snaps to the frame, updates existing keys in place, and handles numeric, color, and effect values with easing.

Instructions

Insert or update one key on a layer param by time (t_us, timeline-absolute), snapped to the frame first: a key on that frame is updated in place, id kept. On a Static track the first key replaces the static value, which is not kept — key the start value too, or use set_param_track. value is typed by param_key: a number, or {r,g,b,a} (0..255) for "color"; an effect param needs no prior write and must sit in its catalog range. easing eases the segment leaving the key, or on the last key the one arriving at it; omitted, a new key inherits the easing of the segment it splits. Returns the key (keyframe_id, t_us, local_t_us). Sides, continuity, Auto tangents: update_keyframe.

Input Schema

NameRequiredDescriptionDefault
t_usYesKey time, timeline-absolute, µs.
valueYesTyped by `param_key`: a number for scalar params (x, y, path_progress, scale_x, scale_y, rotation_deg, anchor_x, anchor_y, opacity, gain_db, pan, effect params), {r,g,b,a} (0..255) for "color". Path mode takes path_progress (a fraction) instead of x/y.
easingNoEasing of the segment leaving the key (on the last key, the one arriving at it): {"preset":"<id>"} or a raw {"kind":...}. Writes this key's out/segment and the next key's in.
layer_idYesLayer id.
param_keyYesVisual: x/y (XY), path_progress (Path), scale_x, scale_y, rotation_deg, anchor_x, anchor_y, opacity; Text/Color: color; Audio: gain_db, pan; effects[<effect_id>].params[<key>].

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.6.0
    • addedInput schema / properties / easing
      Added value: +{
+  "description": "Easing of the segment leaving the key (on the last key, the one arriving at it): {\"preset\":\"<id>\"} or a raw {\"kind\":...}. Writes this key's out/segment and the next key's in.",
+  "properties": {
+    "amplitude": {
+      "description": "Elastic only: overshoot amplitude, >= 1. Omit for the default 1.",
+      "type": "number"
+    },
+    "dir": {
+      "description": "Elastic/Bounce only: easing direction.",
+      "enum": [
+        "In",
+        "Out",
+        "InOut"
+      ],
+      "type": "string"
+    },
+    "kind": {
+      "description": "A raw easing kind, instead of a preset.",
+      "enum": [
+        "Hold",
+        "Linear",
+        "Bezier",
+        "Elastic",
+        "Bounce"
+      ],
+      "type": "string"
+    },
+    "p1": {
+      "description": "Bezier only: first control point [x, y]; x within [0, 1].",
+      "items": {
+        "type": "number"
+      },
+      "maxItems": 2,
+      "minItems": 2,
+      "type": "array"
+    },
+    "p2": {
+      "description": "Bezier only: second control point [x, y]; x within [0, 1].",
+      "items": {
+        "type": "number"
+      },
+      "maxItems": 2,
+      "minItems": 2,
+      "type": "array"
+    },
+    "period": {
+      "description": "Elastic only: oscillation period, > 0. Omit for the default 0.3.",
+      "type": "number"
+    },
+    "preset": {
+      "description": "Preset id from the canonical easing table (e.g. \"ease_in_out\", \"ease_out_expo\"); read back in preset_ids.",
+      "enum": [
+        "linear",
+        "hold",
+        "ease",
+        "ease_in",
+        "ease_out",
+        "ease_in_out",
+        "ease_in_sine",
+        "ease_out_sine",
+        "ease_in_out_sine",
+        "ease_in_quad",
+        "ease_out_quad",
+        "ease_in_out_quad",
+        "ease_in_cubic",
+        "ease_out_cubic",
+        "ease_in_out_cubic",
+        "ease_in_quart",
+        "ease_out_quart",
+        "ease_in_out_quart",
+        "ease_in_quint",
+        "ease_out_quint",
+        "ease_in_out_quint",
+        "ease_in_expo",
+        "ease_out_expo",
+        "ease_in_out_expo",
+        "ease_in_circ",
+        "ease_out_circ",
+        "ease_in_out_circ",
+        "ease_in_back",
+        "ease_out_back",
+        "ease_in_out_back",
+        "ease_in_elastic",
+        "ease_out_elastic",
+        "ease_in_out_elastic",
+        "ease_in_bounce",
+        "ease_out_bounce",
+        "ease_in_out_bounce"
+      ],
+      "type": "string"
+    }
+  },
+  "required": [],
+  "type": "object"
+}
    • removedInput schema / properties / interp
      Removed value: -{
-  "description": "Easing: {\"kind\":\"Hold\"} | {\"kind\":\"Linear\"} | {\"kind\":\"Bezier\",\"p1\":[x,y],\"p2\":[x,y]} | {\"kind\":\"Elastic\",\"dir\",amplitude?,period?} | {\"kind\":\"Bounce\",\"dir\"}.",
-  "properties": {
-    "amplitude": {
-      "description": "Elastic only: overshoot amplitude, >= 1. Omit for the default 1.",
-      "type": "number"
-    },
-    "dir": {
-      "description": "Elastic/Bounce only: easing direction.",
-      "enum": [
-        "In",
-        "Out",
-        "InOut"
-      ],
-      "type": "string"
-    },
-    "kind": {
-      "description": "Easing kind of the segment leaving the key.",
-      "enum": [
-        "Hold",
-        "Linear",
-        "Bezier",
-        "Elastic",
-        "Bounce"
-      ],
-      "type": "string"
-    },
-    "p1": {
-      "description": "Bezier only: first control point [x, y]; x within [0, 1].",
-      "items": {
-        "type": "number"
-      },
-      "maxItems": 2,
-      "minItems": 2,
-      "type": "array"
-    },
-    "p2": {
-      "description": "Bezier only: second control point [x, y]; x within [0, 1].",
-      "items": {
-        "type": "number"
-      },
-      "maxItems": 2,
-      "minItems": 2,
-      "type": "array"
-    },
-    "period": {
-      "description": "Elastic only: oscillation period, > 0. Omit for the default 0.3.",
-      "type": "number"
-    }
-  },
-  "required": [
-    "kind"
-  ],
-  "type": "object"
-}
  2. Changed1 schema field changedv0.2.2
    • changedInput schema / properties / param_key / description
      Previous value: -"Animatable param: visual kinds x, y (path_progress in Path mode), scale_x, scale_y, rotation_deg, anchor_x, anchor_y, opacity; Text and Color color; Audio gain_db, pan; or an effect param as effects[<effect_id>].params[<key>]."New value: +"Visual: x/y (XY), path_progress (Path), scale_x, scale_y, rotation_deg, anchor_x, anchor_y, opacity; Text/Color: color; Audio: gain_db, pan; effects[<effect_id>].params[<key>]."
  3. Changed7 schema fields changedv0.1.9
    • addedInput schema / properties / interp / properties / kind / description
      Added value: +"Easing kind of the segment leaving the key."
    • addedInput schema / properties / layer_id / description
      Added value: +"Layer id."
    • addedInput schema / properties / param_key / anyOf
      Added value: +[
+  {
+    "enum": [
+      "x",
+      "y",
+      "path_progress",
+      "scale_x",
+      "scale_y",
+      "rotation_deg",
+      "anchor_x",
+      "anchor_y",
+      "opacity",
+      "color",
+      "gain_db",
+      "pan"
+    ]
+  },
+  {
+    "pattern": "^effects\\[[0-9a-fA-F-]{36}\\]\\.params\\[[A-Za-z0-9_]+\\]$"
+  }
+]
    • addedInput schema / properties / param_key / description
      Added value: +"Animatable param: visual kinds x, y (path_progress in Path mode), scale_x, scale_y, rotation_deg, anchor_x, anchor_y, opacity; Text and Color color; Audio gain_db, pan; or an effect param as effects[<effect_id>].params[<key>]."
    • addedInput schema / properties / t_us / description
      Added value: +"Key time, timeline-absolute, µs."
    • changedInput schema / properties / value / description
      Previous value: -"Typed by `param_key`: a number for every scalar param (x, y, path_progress, scale_x, scale_y, rotation_deg, anchor_x, anchor_y, opacity, gain_db, pan, effect params); an {r,g,b,a} colour (integers 0..255) for \"color\" — the Text and Color layers' colour. Path mode rejects independent x/y writes; use path_progress (a fraction, not a percentage); XY mode has no path_progress. A mismatch is refused naming the type the param takes."New value: +"Typed by `param_key`: a number for scalar params (x, y, path_progress, scale_x, scale_y, rotation_deg, anchor_x, anchor_y, opacity, gain_db, pan, effect params), {r,g,b,a} (0..255) for \"color\". Path mode takes path_progress (a fraction) instead of x/y."
    • removedInput schema / properties / value / oneOf
      Removed value: -[
-  {
-    "type": "number"
-  },
-  {
-    "properties": {
-      "a": {
-        "type": "integer"
-      },
-      "b": {
-        "type": "integer"
-      },
-      "g": {
-        "type": "integer"
-      },
-      "r": {
-        "type": "integer"
-      }
-    },
-    "required": [
-      "r",
-      "g",
-      "b",
-      "a"
-    ],
-    "type": "object"
-  }
-]
  4. First observedv0.1.8

TDQS

A4.6/5.0
Behavior4/5

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

Goes well beyond the annotations (which only declare idempotent, non-destructive, closed-world): it discloses the snap-to-frame reconciliation rule, that an existing key is updated in place with its id preserved, and the important caveat that a Static track's static value is discarded. The easing inheritance default for a split segment is another non-obvious behavior. It stops short of describing failure modes (e.g. out-of-catalog effect range errors), keeping it at 4 rather than 5.

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-loaded with the core action and tightly written with zero filler sentences; every clause carries a rule an agent needs. It is dense — heavy backticking, parentheticals and semicolon chains make it slower to scan than it could be — but nothing is redundant.

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?

There is no output schema, and the description compensates by stating the return shape (`keyframe_id`, `t_us`, `local_t_us`). Combined with the snap rule, static-track caveat, value typing and easing defaults, an agent has everything needed to call this correctly for a 5-parameter nested-schema mutation tool.

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 above that by adding semantics the schema lacks — that `value` is typed by `param_key` (number vs {r,g,b,a} 0..255), that an effect param needs no prior write but must sit in its catalog range, and that omitted `easing` makes a new key inherit the easing of the segment it splits. The `easing` object itself is left to the schema.

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 precise verb+resource ("Insert or update one key on a layer param by time") and immediately qualifies scope with the timeline-absolute unit and snap-to-frame rule. It distinguishes itself from siblings by naming set_param_track for static values and update_keyframe for sides/continuity/Auto tangents, so an agent can route correctly without opening another 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?

Explicitly states when to deviate: on a Static track the first key replaces the static value, so either key the start value too or use set_param_track instead. It also redirects tangent/continuity work to update_keyframe. Both alternatives are named with the condition that selects them.

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

Deploy Server

Other Tools