Add token-efficient tools: batch arrangement, guarded deletes, combined instrument creation, volume automation, sync check

[M4x28]

PR: Token-efficient AbletonMCP (batch ops, guarded deletes, combined creation, volume + sync)

Summary

Reduces LLM token use and round trips, and adds capability, without changing the socket protocol style. Verified live on Ableton Live 12.4.2. On a full 3 minute arrangement the command count drops 91% (354 to 31), exact tokens drop 80% (33,521 to 6,804), and build time drops 89% (262s to 29s), while the optimized path also does volume automation and a sync check that the old path cannot.

What changed

Server exposes 32 tools (was 21). 11 new tools, plus a token diet on the existing ones.

New tools:

• duplicate_to_arrangement_batch(track, clip, destination_time, count, spacing): place N copies in one call (spacing 0 = gapless).
• create_instrument_track(name, uri, clip_length, notes, clip_name): create track + name + load instrument + clip + notes in one call.
• get_tracks_overview(): compact list of all tracks (one call vs N verbose get_track_info).
• get_notes_from_clip(track, clip): read existing MIDI notes so edits are not guesses.
• delete_clip, clear_clip_notes, delete_arrangement_clips, delete_track: destructive ops with a two phase confirm guardrail (a call without confirm=true returns a preview and changes nothing).
• set_track_volume(track, value): static mixer volume.
• create_volume_fade(track, clip_index, from_value, to_value): volume automation fade on a Session clip (rides into the arrangement when duplicated). The Live API only allows automation on Session clips, so fades are authored there.
• check_arrangement_sync(bar_beats): compact grid alignment report (off_grid, overlaps, gaps counts plus only the problem clips).

Token diet on existing tools:

• Removed the user_prompt parameter from all 21 original tools (42 sites). It forced the model to resend the whole prompt on every call.
• Compact JSON on the 4 read tools (indent=2 to separators).

Guardrail

Deletes use a two phase confirm because an MCP call cannot pause for human input mid call. Without confirm=true the tool runs a dry run and returns exactly what would be removed; the human approves and re calls with confirm=true.

Breaking / behavior notes for the maintainer

• Removing user_prompt disables prompt based telemetry. The decorator degrades to None, so nothing breaks, but if you want to keep prompt telemetry, make it an opt in env var instead.
• Live API constraints: create_audio_clip needs Live 12.0.5+, arrangement volume automation is authored on Session clips (documented in the tool).
• Version bumped to 1.2.1.

Files

• MCP_Server/server.py: see PR_server.py.patch
• AbletonMCP_Remote_Script/__init__.py: see PR_remote_script.__init__.py.patch

Verification

py_compile clean, FastMCP loads 32 tools, user_prompt absent from every schema. All new endpoints tested live on a scratch track that was created and deleted. Full benchmark, charts and two audible demo sets in the attached report.

---

Demo sets (download and open in Live 12)

These Ableton sets let a reviewer hear the output. They use only Live 12 factory devices (DS Kick/HH/Clap, Acid Bass, 303), so no external samples are needed.

• techno_acid_3min_140.als: the full 3 minute arrangement with sections, mix and fades.
• techno_acid_optimized.als and techno_acid_original.als: the 16 bar short test, identical music built by each workflow, for an A/B listen.

These files live on the fork's pr-assets branch and are not part of the code diff.

---

Appendix A: Benchmark, round 2 (exact tokens, new endpoints, 3-minute track)

AbletonMCP Optimization, Round 2: exact tokens, new endpoints, 3-minute track

This round answers four requests: measure exact tokens (not an estimate), report a real end to end wall clock, reduce the cost of the sample creation phase, and add a long benchmark that builds a full 3 minute arrangement using two brand new endpoints. Everything below was run live against Ableton Live 12.4.2.

Method

Tokens are counted with a real BPE tokenizer (tiktoken o200k_base) applied to the exact request and response strings of every call. This is an exact integer count, not a characters divided by four estimate. Claude's own tokenizer is not published for offline use, so a real tokenizer is the closest exact and reproducible measure.

Wall clock is a single real timer around the whole run, from the first call to the last, reported as measured. It covers the connector plus Ableton execution. It does not include model inference time, so a real chat session would be slower on both versions, and more so on the original because it fires far more calls.

Two new endpoints (plus one that cuts phase 1)

Endpoint	What it does	Live test
create_volume_fade	Writes a volume automation fade on a Session clip that rides into the arrangement when the clip is placed. Used for intro fade in and outro fade out.	Pass, verified the envelope and insert_step API, fade 0.0 to 0.9 written
check_arrangement_sync	Reports whether arrangement clips are grid aligned across all tracks. Returns compact counts (off grid, overlaps, gaps) plus only the problem clips.	Pass, on the 3 minute track: 328 clips, off grid 0, overlaps 0, in sync true
set_track_volume	Sets a track mixer volume for static section balance.	Pass
create_instrument_track	Collapses create track, name, load instrument, create clip and add notes into ONE call, and names the clip. This is the phase 1 cost fix.	Pass

The Live API only allows volume automation on Session clips, so create_volume_fade writes the fade there and the arrangement inherits it when the clip is duplicated. That is why the intro and outro use dedicated 8 bar section clips.

The connector fork now exposes 32 tools. All four endpoints were tested on a scratch track that was created and deleted, leaving the set unchanged.

Short benchmark (16 bar loop), exact numbers

Same acid track built twice: five instruments (kick, acid bass, hat, clap, acid melody) then a 16 bar arrangement. Identical music, so the only difference is the connector.

Metric	Original	Optimized	Change
Tool calls	88	13	down 85 percent
Tokens (exact)	8,207	2,023	down 75 percent
Wall clock	64.8 s	11.9 s	down 82 percent
Phase 1 tokens (create samples)	2,978	1,492	down 50 percent
Phase 1 calls	25	5	down 80 percent

The sample creation phase now costs half as much and does more: create_instrument_track builds each instrument in one call and also names its clip. So the optimized version is cheaper and better organised at the same time, which was the request.

Long benchmark: full 3 minute acid track at 140 BPM

The long test builds a real arrangement with intro, build, drop, break, climax and outro across 104 bars (about 3:12 at 140 BPM). The optimized run also adds a static mix, an intro fade in on the kick, an outro fade out on the bass, and a final synchronization check. The original run reproduces the same notes and arrangement with the old command style (one clip placement per call, prompt echoed on every call) and cannot do the automation or the check at all.

Metric	Original	Optimized	Change
Tool calls	354	31	down 91 percent
Tokens (exact)	33,521	6,804	down 80 percent
Wall clock	262.2 s	29.4 s	down 89 percent

The arrangement phase is where the gap explodes: 327 individual placements on the original become 10 batch calls on the optimized version, and the placement cost drops from about 30,100 tokens to 602. The optimized total still includes roughly 4,557 tokens of volume automation work that the original simply cannot perform, so the optimized version does more and still costs 80 percent less.

The synchronization check confirmed the result: 328 arrangement clips, zero off grid, zero overlaps, in sync true. The four gaps it reports are the intentional silences of the break and the section entries, which the endpoint lists separately rather than treating as errors.

Deliverables

File	What it is
techno_acid_3min_140.als	The full 3 minute arrangement with sections, mix and fades, open in Live 12 to judge the result
techno_acid_optimized.als, techno_acid_original.als	The 16 bar short test tracks, identical music, for an A B listen
bench2_long_phases.png, bench2_totals.png	The charts above
short_exact.json, long_exact.json	The raw exact token and timing data

Notes

The token figures use a real tokenizer, so treat them as exact for that tokenizer; Claude's absolute counts differ slightly but the relative reductions hold. The wall clock is the measured end to end time of each run. The four connector endpoints added this round are all verified live and shipped in the fork, which now carries 32 tools and activates on the next Claude Desktop restart.

---

Appendix B: First benchmark (16-bar build, original vs optimized)

AbletonMCP Benchmark - Techno Acid Track, End-to-End

Same track built twice through the same Ableton Live 12.4.2 + AbletonMCP socket, once with the original v1.2.0 command style, once with the optimized fork. Music is byte-identical between runs (.als 60,336 vs 60,351 B), so any difference is purely connector efficiency.

1. Method

• Two phases per run: (1) create one instrument/sample per part, (2) build the 16-bar arrangement.
• What differs by version: original sends user_prompt on every tool call and places arrangement clips one-by-one; optimized drops user_prompt, uses duplicate_to_arrangement_batch, and uses the compact get_tracks_overview.
• Metrics: tool calls (round trips), LLM-side tokens (modeled: request args the model emits + text the server returns; user_prompt counted for original, indent=2 vs compact for reads), wall-clock seconds (real, measured over the socket).
• Token proxy: chars ÷ 4. Relative % is near tokenizer-invariant; absolute tokens are ballpark.

2. The track (identical in both runs)

130 BPM, A minor. Five parts, each its own MIDI track + device + 1 Session clip, then arranged.

Part	Device (Live factory)	Browser URI	Pattern	Arrangement
Kick	DS Kick	query:Synths#DS%20Kick	4-on-floor, C1	bars 1-16 (×16)
Bass	Acid Bass (303)	query:Sounds#Bass:FileId_6970	16th-note acid line, A1 w/ octave/fifth + accents	bars 1-16 (×16)
Hat	DS HH	query:Synths#DS%20HH	offbeat 8ths + 16th ghosts	bars 5-16 (×12)
Clap	DS Clap	query:Synths#DS%20Clap	beats 2 & 4	bars 5-16 (×12)
Melody	Basic 303 Bass	query:Sounds#Bass:FileId_5239	2-bar A-minor pentatonic acid riff	bars 9-16 (×4)

Structure: intro (kick+bass) → build (add hat+clap) → drop (add acid melody). 60 arrangement clips total.

3. Results

Metric	Original v1.2.0	Optimized fork	Reduction
Tool calls (round trips)	88	33	−62%
Tokens (LLM-side)	7,676	2,064	−73%
Wall-clock time	61.6 s	26.3 s	−57%

Per phase

Phase	Metric	Original	Optimized	Reduction
Setup (orient + tempo)	calls / tok / s	2 / 192 / 1.3	2 / 143 / 1.0	tok −26%
Phase 1 - create samples	calls / tok / s	25 / 2,573 / 18.4	25 / 1,654 / 20.8	tok −36%
Phase 2 - arrangement	calls / tok / s	61 / 4,911 / 41.9	6 / 267 / 4.5	calls −90%, tok −95%, time −89%

Reading it:

• Phase 2 is where the connector wins: 61 individual duplicate calls collapse to 5 batch calls (+1 view switch). Tokens −95%, time −89%.
• Phase 1 has the same call count (5 parts × 5 steps) - the −36% token cut is 100% the removed user_prompt echo (~27 tok × 25 calls). Its wall-clock is instrument-load-bound, so the ~2 s difference is noise, not signal.
• Real-world gap is larger than the wall-clock shown: each of the 55 extra original calls is also a full LLM inference round trip (seconds) that the socket timing does not capture.

4. Design decisions & changes (one by one)

#	Change	Type	Rationale	Effect in this benchmark
1	Remove user_prompt from all 21 tools	Token diet	Original forced the model to resend the whole prompt every call; telemetry-only value; degrades to None cleanly	−36% Phase 1 tokens, −26% setup tokens
2	duplicate_to_arrangement_batch(count, spacing)	New tool	N-copy loop was 1 call/clip; spacing=0 = gapless by clip length	Phase 2: 60 calls → 5; −95% tokens
3	get_tracks_overview	New tool	One compact call vs get_session_info + N verbose get_track_info to orient	Setup read compact vs verbose
4	Compact JSON (indent=2 → separators) on 4 reads	Token diet	Indentation is pure whitespace tokens	Smaller read payloads
5	get_notes_from_clip	New tool	Lets the model edit existing notes instead of guessing	Not exercised here (build-only)
6	delete_clip / clear_clip_notes / delete_arrangement_clips / delete_track, two-phase confirm	New tools + guardrail	Deletes were impossible; MCP can't block for human input, so preview-then-confirm=true keeps a human in the loop	Not exercised here (build-only)

Full connector rationale and rollback: see AbletonMCP_optimization_casestudy.md. Code diffs: server.py.patch, remote_script.__init__.py.patch.

5. Deliverables (for qualitative A/B)

• techno_acid_original.als - built via original workflow
• techno_acid_optimized.als - built via optimized workflow

Both open in Ableton Live 12 (factory devices only, no external samples). They are sonically identical by construction - open either to judge the musical result; use the metrics above to judge the connector.

6. Caveats

• Token counts are a chars/4 proxy, not the exact Anthropic tokenizer - trust the %, not the absolute.
• Wall-clock measured over the socket (Ableton execution + transport), excluding LLM inference latency, which would widen the gap further for the original.
• Phase 1 timing is dominated by factory-instrument loading and varies run-to-run.

---

Appendix C: Design decisions and rationale

Full design notes and rollback steps are in AbletonMCP_optimization_casestudy.md (attached). Key points are summarised in the PR body above.