Live Maestro

Overview Schema Source Related Servers Discussions Admin

arrange

Copy Session clips onto the Arrangement timeline at specified beat positions, preserving the source clips so each copy can be edited independently.

Instructions

Copy Session clips onto the Arrangement timeline at beat positions.

Supports two modes:
1. Single placement: specify track, slot, at_beat (and optionally to_track).
2. Batch placements: pass a placements list to duplicate several clips and verify
   each one against the destination track it landed on.

A copy, not a move: the Session clip stays in its slot and the two are separate
clips afterwards, so editing one leaves the other alone. This is how a Session
idea becomes an arrangement, and how clip automation written by write_automation
reaches the Arrangement timeline.

Returns:
    For single placement: dictionary with placement status, destination track,
    clip counts before and after, the beat the clip actually landed on, and the
    clip itself under placed_clip. Both modes identify a placement by comparing the
    destination track before and after, so a clip that was already on the requested
    beat never stands in for one that did not land.
    For placements list: dictionary with per-placement requested_beat, actual_beat,
    ok, and summary counts.

Note:
    Call it once per placement. Repeating the same call adds another copy at the
    same beat rather than replacing the first, so a retry after an unclear result
    needs the clip count in this answer checked first.

    A list retries worse than a single call, not better: a list that half landed
    doubles what landed if it is sent again. 'destinations' carries the clip count
    per destination track before and after, which is the number to check first.

    Use create_clip and write_clip_notes to build the source clip, and
    set_arrangement_time then play to hear where it landed.

Input Schema

TableJSON Schema

Name	Required	Description
`slot`	No	Clip slot index in track.clip_slots, counted from 0. A slot index is the scene the clip sits in, so slot 2 is the third scene down. Required if placements is omitted.
`track`	No	Track index in song.tracks, counted from 0. Required if placements is omitted.
`at_beat`	No	Where the copy starts on the Arrangement timeline, in beats from the start of the song. Fractional beats are accepted. Required if placements is omitted.
`to_track`	No	Track index to place the copy on. Omit to use the source track, which is the usual case. A MIDI clip needs a MIDI destination.
`placements`	No	List of placements to duplicate onto the Arrangement timeline, each verified against the destination track it landed on: [{"track": 0, "slot": 1, "at_beat": 64.0, "to_track": null}, ...]. A long list is chunked across several round trips rather than refused. When provided, the single-placement parameters (track, slot, at_beat) must be omitted, including to_track, which each placement carries itself.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed15 schema fields changedSep 24, 2026

addedInput schema / properties / at_beat / anyOf

Added value: +[
+  {
+    "type": "number"
+  },
+  {
+    "type": "null"
+  }
+]

addedInput schema / properties / at_beat / default
```
Added value: +null
```

changedInput schema / properties / at_beat / description

Previous value: -"Where the copy starts on the Arrangement timeline, in beats from the start of the song. Fractional beats are accepted."New value: +"Where the copy starts on the Arrangement timeline, in beats from the start of the song. Fractional beats are accepted. Required if placements is omitted."

removedInput schema / properties / at_beat / type
```
Removed value: -"number"
```

addedInput schema / properties / placements

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "additionalProperties": false,
+        "description": "One clip placement from a Session slot onto the Arrangement timeline.",
+        "properties": {
+          "at_beat": {
+            "description": "Where the copy starts on the Arrangement timeline, in beats from the start of the song. Fractional beats are accepted.",
+            "title": "At Beat",
+            "type": "number"
+          },
+          "slot": {
+            "description": "Clip slot index in track.clip_slots, counted from 0.",
+            "minimum": 0,
+            "title": "Slot",
+            "type": "integer"
+          },
+          "to_track": {
+            "anyOf": [
+              {
+                "minimum": 0,
+                "type": "integer"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "description": "Destination track index. Omit to use the source track, which is the usual case.",
+            "title": "To Track"
+          },
+          "track": {
+            "description": "Source track index in song.tracks, counted from 0.",
+            "minimum": 0,
+            "title": "Track",
+            "type": "integer"
+          }
+        },
+        "required": [
+          "track",
+          "slot",
+          "at_beat"
+        ],
+        "title": "PlacementIn",
+        "type": "object"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "List of placements to duplicate onto the Arrangement timeline, each verified against the destination track it landed on: [{\"track\": 0, \"slot\": 1, \"at_beat\": 64.0, \"to_track\": null}, ...]. A long list is chunked across several round trips rather than refused. When provided, the single-placement parameters (track, slot, at_beat) must be omitted, including to_track, which each placement carries itself.",
+  "title": "Placements"
+}

addedInput schema / properties / slot / anyOf

Added value: +[
+  {
+    "minimum": 0,
+    "type": "integer"
+  },
+  {
+    "type": "null"
+  }
+]

addedInput schema / properties / slot / default
```
Added value: +null
```

changedInput schema / properties / slot / description

Previous value: -"Clip slot index in track.clip_slots, counted from 0. A slot index is the scene the clip sits in, so slot 2 is the third scene down."New value: +"Clip slot index in track.clip_slots, counted from 0. A slot index is the scene the clip sits in, so slot 2 is the third scene down. Required if placements is omitted."

removedInput schema / properties / slot / type
```
Removed value: -"integer"
```

changedInput schema / properties / to_track / anyOf

Previous value: -[
-  {
-    "type": "integer"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "minimum": 0,
+    "type": "integer"
+  },
+  {
+    "type": "null"
+  }
+]

addedInput schema / properties / track / anyOf

Added value: +[
+  {
+    "minimum": 0,
+    "type": "integer"
+  },
+  {
+    "type": "null"
+  }
+]

addedInput schema / properties / track / default
```
Added value: +null
```

changedInput schema / properties / track / description

Previous value: -"Track index in song.tracks, counted from 0."New value: +"Track index in song.tracks, counted from 0. Required if placements is omitted."

removedInput schema / properties / track / type
```
Removed value: -"integer"
```

removedInput schema / required

Removed value: -[
-  "track",
-  "slot",
-  "at_beat"
-]

Changed4 schema fields changedv0.1.1Sep 7, 2026

addedInput schema / properties / at_beat / description

Added value: +"Where the copy starts on the Arrangement timeline, in beats from the start of the song. Fractional beats are accepted."

addedInput schema / properties / slot / description

Added value: +"Clip slot index in track.clip_slots, counted from 0. A slot index is the scene the clip sits in, so slot 2 is the third scene down."

addedInput schema / properties / to_track / description

Added value: +"Track index to place the copy on. Omit to use the source track, which is the usual case. A MIDI clip needs a MIDI destination."

addedInput schema / properties / track / description

Added value: +"Track index in song.tracks, counted from 0."

First observedv0.1.0Sep 5, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Annotations are minimal (readOnlyHint=false, idempotentHint=false, destructiveHint=false), but the description goes well beyond them. It clarifies non-destructive copy behavior, explains that repeated calls add duplicates (non-idempotent), details the return structure and how to detect placement failures, and notes that long lists are chunked. It even warns about the risk of re-sending partially-successful lists. This is rich behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is structured logically: purpose, modes, copy semantics, return details, and practical notes. It is comprehensive without redundancy; every sentence adds information. Front-loading the core purpose and modes ensures agents quickly grasp the tool's function, while the later notes address edge cases. It is long but efficient for the tool's complexity.

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?

Given the tool's complexity (two modes, 5 parameters, output schema present), the description covers return values, usage patterns, and common pitfalls. It explains how to verify results, warns about retry behavior, and integrates with surrounding tools (create_clip, write_automation). The presence of an output schema reduces the need to describe return fields, and the description still adds operational context. Nothing critical is missing.

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 adds value by explaining the two modes and how parameters interact (e.g., to_track omitted for source track, MIDI needs MIDI destination, placements list omits single-placement parameters). It also clarifies the meaning of at_beat with fractional beats and the verification logic. This goes beyond the schema, justifying a 4.

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 precise action: 'Copy Session clips onto the Arrangement timeline at beat positions.' It then distinguishes two operational modes (single vs. batch) and explicitly states it is a copy, not a move, making the tool's role unambiguous. It also connects to related workflows (write_automation, create_clip) without confusing it with siblings.

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?

It explicitly states when to use this tool: 'This is how a Session idea becomes an arrangement, and how clip automation... reaches the Arrangement timeline.' It also gives guidance on building the source clip with create_clip and write_clip_notes, and how to verify placement with set_arrangement_time and play. It warns against retries and explains the difference between single and list calls, providing clear when/why guidance.

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