Skip to main content
Glama

build_arrangement

Lays out your Ableton Arrangement section by section, tiling active Session clips per section with named locators and clip-envelope automation applied as track automation.

Instructions

Build the Arrangement from Session clips, section by section, like a producer laying out a track: each section plays the clips of the tracks whose role is active there, tiled to fill it, with a named locator at its start. Clip envelopes (see write_clip_evolution) come along as track automation, so a filter build or a reverb swell plays in the Arrangement.

Use a template (techno_dj, techno_64, minimal, house; see arrangement_templates) or your own sections: [{"name", "bars", "roles": [...]} or {"name", "bars", "play": {"track_index": slot}}]. Track roles come from track names (kick, drums, hats, perc, rumble, bass, chords, pad, lead, vocal, fx) unless track_roles {"track_index": role} overrides them. section_slots {"Section name": {"track_index": slot}} picks another clip for a section (e.g. the automated build variant). Run with dry_run=true first to see the plan.

Parameters:

  • template / sections: Structure to build

  • track_roles: Role per track index, overriding names

  • start_bar: Arrangement bar to start at (0 = beginning)

  • default_slot: Session slot used by default for every track

  • section_slots: Per-section slot overrides

  • locators: Add a locator at each section (transport must be stopped)

  • dry_run: Only return the plan

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": "build_arrangement"
  }
}

Input Schema

NameRequiredDescriptionDefault
dry_runNo
locatorsNo
sectionsNo
templateNo
start_barNo
track_rolesNo
default_slotNo
section_slotsNo

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv2.1.1

TDQS

A4.3/5.0
Behavior4/5

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

With no annotations, the description carries the burden and does a lot: it explains that clips are tiled to fill each section, that a named locator is placed at each section start, that clip envelopes are converted into track automation, and that adding locators requires the transport to be stopped. What it omits is the destructive dimension — whether existing Arrangement content is overwritten, appended after `start_bar`, or left in place — which matters most for a builder that writes into a live project.

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?

Three short paragraphs plus a parameter list, with the core action front-loaded and the dry-run warning placed correctly at the end of the usage block. The "like a producer laying out a track" simile is decorative, and the parameter bullets partially restate what the prose already said, but neither costs much.

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 an eight-parameter tool with nested objects, the description covers structure, roles, slot overrides, locator side effects, and dry-run preview, and an output schema exists so return values need no explanation. It is not fully complete because the effect on pre-existing Arrangement content and the error/precondition surface beyond locators are unstated.

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 0%, so the description must compensate and largely does: it enumerates the valid templates, gives the exact JSON shape for `sections` in both forms, lists the canonical role names, and explains that `track_roles` overrides name-derived roles and `section_slots` overrides the default slot per section. Remaining gaps are the two nested-object parameters' edge cases (conflicting or unknown section names, out-of-range track_index) and what `start_bar`/existing content interaction means.

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?

"Build the Arrangement from Session clips, section by section" is a specific verb plus resource, and the description immediately differentiates the tool from arrangement_templates (which supplies templates) and from write_clip_evolution (which writes the envelopes this tool consumes). An agent can tell what this does and how it differs from the surrounding arrangement tools without opening 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: use a named template or supply your own `sections`, prefer `track_roles` over inferred track names when they're wrong, use `section_slots` for an alternate clip such as the automated build variant, and "Run with dry_run=true first to see the plan." It stops short of naming explicit alternatives/exclusions against siblings like duplicate_to_arrangement or record_arrangement, so it's clear context rather than a full routing rule.

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