Skip to main content
Glama

transform_clip

Rearranges a MIDI clip by applying an ordered chain of music-theory operations, writing the result to the original clip or an empty Session slot.

Instructions

Re-arrange a MIDI clip with a chain of music-theory operations, applied in order. Writes the result back into the clip, or into an empty Session slot target_clip_index (keeps the original: safer for trying ideas).

Each operation is {"op": name, ...arguments}:

  • transpose: semitones

  • transpose_diatonic: steps, root, scale (moves along the scale)

  • change_mode: root, from_scale, to_scale[, to_root] (C major -> C dorian...)

  • snap_to_scale: root, scale[, direction nearest|up|down]

  • invert: axis ("C4" or 60)[, root, scale for a diatonic mirror]

  • retrograde: [length]

  • time_scale: factor (2 = half speed, 0.5 = double)

  • quantize: [grid=0.25, strength=1.0, durations=false]

  • swing: [amount_pct=60 (50 straight, 66.7 triplet), grid=0.5]

  • humanize: [timing=0.01 beats, velocity=8, seed=0]

  • accent: [pattern=[1,0.7,0.85,0.7], grid=1.0, base=110]

  • articulate: factor (0.5 = staccato) or legato=true

  • fold_range: low, high (e.g. "C3", "C5")

  • harmonize: root, scale[, steps=[2] (2 = third above, -2 below, 4 fifth, 5 sixth), keep_original=true]

  • arpeggiate: [rate=0.25, pattern up|down|updown|random, octaves=1, gate=0.9]

  • strum: [spread=0.03, direction down|up]

  • voice_chords: voicing close|drop2|open|spread Notes are written as C4 = MIDI 60 (Live displays it as C3).

Parameters:

  • track_index / clip_index: Source clip

  • operations: List of operations (see above)

  • location: "session" (default) or "arrangement"

  • target_clip_index: Empty Session slot on the same track for the result (optional)

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>",
      "operations": "<operations>"
    },
    "name": "transform_clip"
  }
}

Input Schema

NameRequiredDescriptionDefault
locationNosession
clip_indexYes
operationsYes
track_indexYes
target_clip_indexNo

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv2.1.1

TDQS

A4.4/5.0
Behavior4/5

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

With no annotations at all, the description carries the full burden and does disclose the key mutation behavior: results are written into the clip (overwriting it) unless a target slot is supplied, in which case the original is preserved. It does not say what happens if target_clip_index is occupied or whether unrecognized/invalid operations fail atomically, so irreversibility and error semantics remain partly unstated.

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?

The lead sentence is front-loaded and the operation catalog is scannable, one op per line with defaults inline, so the length is justified by the domain. The trailing 'Parameters:' block partly restates schema property names, though it does add meaning (source clip, empty Session slot on same track) and the C4=MIDI 60 note is a necessary disambiguation for Live's display convention.

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 5-parameter mutation tool with an output schema (so return values need no explanation), the description covers purpose, target selection, and the entire operation grammar. The remaining gap is edge-case behavior: whether the target slot must be empty, how location='arrangement' behaves, and failure handling for bad operation names.

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 description coverage is 0%, so the description must compensate entirely, and it does: track_index/clip_index are identified as the source clip, location is given as session vs arrangement, and target_clip_index as an empty Session slot on the same track. The bulk of the value is the full operation vocabulary with per-op arguments and defaults (e.g. swing amount_pct=60 with 50=straight, 66.7=triplet; harmonize steps=[2]=third above), which is impossible to infer from the free-form object array 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?

The opening sentence names a specific verb ('Re-arrange') and resource ('a MIDI clip') plus the mechanism ('chain of music-theory operations, applied in order'). That clearly separates it from siblings such as add_notes_to_clip (additive) and analyze_clip_music (read-only) without needing to open any 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 gives real decision guidance for the main fork: write back into the source clip, or pass target_clip_index to route the result into an empty Session slot, explicitly labeled 'safer for trying ideas'. It does not state when to prefer this tool over siblings like write_clip_evolution or add_notes_to_clip, so it stops short of full alternative routing.

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