Skip to main content
Glama

update_clip

Destructive

Modify Session or timeline audio/MIDI clip settings and optionally run an action; omitted fields stay unchanged.

Instructions

Change a clip's settings and optionally run an action; every field you leave empty stays as it is. Works on Session and timeline clips, MIDI and audio.

Settings: name, color, mute, loop and marker positions, time signature, launch mode and quantization, legato, clip scale, groove; for audio also warping, warp mode, gain, pitch and RAM mode. Actions: fire, stop, crop to the loop, duplicate_loop, quantize (grid, amount), clear_envelopes, move_playing_position, and warp markers (add, move, remove). Each field gets a result line with what Live holds afterwards; Live keeps the old value for something it refuses and the line says so. Loop markers that Live refuses in one order are tried again after the others. One undo step.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "update_clip"
  }
}

Input Schema

NameRequiredDescriptionDefault
clipNoThe clip: t0/s2 (Session slot 2 of t0) or t0/a1 (the second timeline clip of t0, see arrangement list). Or give track and slot instead.
gainNoAudio: gain 0-1 (Live's raw scale; the answer shows dB).
gridNoFor quantize: None, 1/4, 1/8, 1/8T, 1/8 + 1/8T, 1/16, 1/16T, 1/16 + 1/16T or 1/32.
nameNoNew clip name.
slotNoSession slot (scene row) from 0, with track.
mutedNoClip deactivated: true / false.
trackNoTrack of a Session clip, e.g. t0 (with slot).
actionNoOptional action to run after the settings.
amountNoFor quantize: strength 0-1 (default 1).
grooveNoA groove from the pool by number or exact name (see groove).
legatoNoLegato launch: true / false.
loopingNoLoop on or off: true / false.
warpingNoAudio: warp on or off: true / false.
loop_endNoLoop end in beats.
ram_modeNoAudio: load the sample into RAM: true / false.
root_noteNoClip scale root as a number 0 (C) to 11 (B).
warp_modeNoAudio: Beats, Tones, Texture, Re-Pitch, Complex or Complex Pro.
end_markerNoEnd marker in beats.
loop_startNoLoop start in beats.
pitch_fineNoAudio: detune in cents, -50 to 50.
scale_modeNoClip scale highlighting on or off: true / false.
scale_nameNoClip scale name as Live shows it: Major, Minor...
time_beatsNoFor move_playing_position and the warp marker actions: a position in beats.
color_indexNoLive's color number, 0-69.
launch_modeNoTrigger, Gate, Toggle or Repeat.
sample_timeNoFor add_warp_marker: the sample position in seconds.
stop_buttonNoSession slot: show or hide its stop button (works on an empty slot).
pitch_coarseNoAudio: transpose in semitones, -48 to 48.
start_markerNoStart marker in beats.
distance_beatsNoFor move_warp_marker: how far to move it, in beats.
time_signatureNoClip time signature such as 3/4.
velocity_amountNoHow much launch velocity scales the clip, -1 to 1.
launch_quantizationNoGlobal, None, 8 Bars, 4 Bars, 2 Bars, 1 Bar, 1/2, 1/2T, 1/4, 1/4T, 1/8, 1/8T, 1/16, 1/16T or 1/32.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.6.1

TDQS

A4/5.0
Behavior5/5

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

Annotations already declare destructiveHint=true and idempotentHint=false, and the description goes well beyond that: per-field result lines showing what Live holds afterwards, the fact that Live silently keeps the old value when it refuses a change, the retry ordering for loop markers refused in one order, and that the whole call is one undo step. These are exactly the residual behaviors an agent cannot get from annotations.

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 mutation contract and partial-update rule, then organized into Settings, Actions, and post-call semantics. It is on the long side and the settings enumeration partially restates what the 100%-covered schema already provides, but the grouping makes it scannable rather than wasteful.

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?

For a 33-parameter mutation tool with no output schema, the description covers the essentials: partial-update behavior, action ordering, return shape ('each field gets a result line'), refusal handling, and undo granularity. What is missing is minor, such as whether Live must be connected or whether concurrent edits are safe.

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 the baseline is 3; the description earns above baseline by grouping the 33 parameters into Settings versus Actions, stating that the action runs after the settings, and pointing out cross-parameter dependencies (quantize needs grid and amount, warp marker actions need time_beats). It does not add format or validation detail beyond the schema for individual fields.

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 verb and resource ('Change a clip's settings and optionally run an action') and scopes it precisely to Session and timeline clips, MIDI and audio, then enumerates the settings and actions available. An agent knows exactly what the tool mutates. It does not name or differentiate itself from adjacent siblings such as write_clip or read_clip, which keeps it from a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

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

The partial-update contract is stated clearly ('every field you leave empty stays as it is'), which tells the agent it can send a single field without clobbering the rest. However there is no explicit when-to-use guidance, no when-not, and no named alternative such as write_clip for full replacements. Usage must be inferred from the enumerated field list.

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