Skip to main content
Glama

set_clip_automation

Draws automation envelopes inside a Session clip for a device parameter or mixer control, so the parameter changes play whenever that clip plays.

Instructions

Draw an automation envelope inside a Session clip; it plays whenever the clip plays. (Live's API does not allow writing envelopes in Arrangement clips or the Arrangement's automation lanes.) Target a device parameter (device_index + parameter_index, see get_device_parameters) or a mixer control (mixer_parameter).

Parameters:

  • track_index: The track holding the clip and the parameter

  • clip_index: The Session slot

  • points: [{"time": 0, "value": 0.2}, {"time": 16, "value": 0.9}] — time in beats from the clip start, value in the parameter's own range (clamped); the last value holds to the clip end. [] with clear_first removes the envelope.

  • location: "session" (the only place Live accepts)

  • device_index: Device in the chain (ignored with mixer_parameter)

  • parameter_index: Parameter of that device

  • mixer_parameter: "volume", "panning" or "send:N" (N = return index)

  • interpolation: "linear" (ramps drawn in steps of resolution) or "step"

  • resolution: Ramp step in beats (0.25 = a sixteenth)

  • clear_first: Erase this parameter's envelope in the clip first

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": {
      "track_index": "<track_index>",
      "clip_index": "<clip_index>",
      "points": "<points>"
    },
    "name": "set_clip_automation"
  }
}

Input Schema

NameRequiredDescriptionDefault
pointsYes
locationNosession
clip_indexYes
resolutionNo
clear_firstNo
track_indexYes
device_indexNo
interpolationNolinear
mixer_parameterNo
parameter_indexNo

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv2.1.1

TDQS

A4.7/5.0
Behavior5/5

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

With no annotations supplied, the description carries the full burden and does so: it discloses that Arrangement writes are impossible via the API, that values are clamped to the parameter's range, that the last point holds to the clip end, that clear_first erases an existing envelope, and that an empty points array with clear_first removes it. Those are exactly the mutation semantics an agent cannot infer from the schema.

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?

Purpose and platform constraint are front-loaded, and the per-parameter bullets are dense with non-redundant information. The only minor waste is restating the session-only restriction in the location bullet after it was already stated in the opening.

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?

For a 10-parameter mutation tool with zero schema documentation and no annotations, this covers targeting, units, defaults, removal behavior, and platform limits; return values need not be described because an output schema exists. Nothing required to call it correctly appears to be missing.

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

Parameters5/5

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

Schema coverage is 0% across 10 parameters, so the description must compensate and does: it defines time units (beats from clip start), value semantics and clamping, the literal mixer_parameter vocabulary ('volume', 'panning', 'send:N'), interpolation modes, resolution units, and the interaction where device_index is ignored when mixer_parameter is set. It also supplies a concrete points example where the schema only declares an untyped number map.

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?

The description opens with a specific verb and resource ('Draw an automation envelope inside a Session clip') and immediately states scope plus the platform restriction that excludes Arrangement clips and lanes. That restriction alone separates it from the arrangement-oriented siblings without the agent needing to open 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 Guidelines4/5

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

It says where the tool applies ('session' is the only place Live accepts), routes the agent to get_device_parameters for index discovery, and explains the two mutually exclusive targeting modes (device_index + parameter_index vs mixer_parameter). It does not point at get_clip_automation as the read-back counterpart, so the when-to-use picture is clear but not fully paired with alternatives.

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