ableton-mcp

Overview Schema Source Related Servers Discussions Admin

propose_audio_transient_warp

Read-onlyIdempotent

Analyze source-audio onsets and propose review-only warp marker actions aligned to a Live beat grid. Reports offsets per candidate for dry-run review before applying.

Instructions

Analyze bounded source-audio onset candidates and propose review-only marker actions toward a beat grid using native Live source-to-beat conversion. Reports signed offsets and one-hop detector resolution in beats for every candidate; suppresses actions within that resolution or competing with a closer onset at the same slot. Optional musical roles label bars, downbeats, quarter pulses and half-beat upbeats from the clip meter. Optional feelBars aggregates one to eight bars of selected onset timing and strength by grid slot; this is not native Groove Pool extraction or baking. Heuristic, source-only, no edit or audible validation; individually dry-run actions against current state before applying.

Input Schema

Name	Required	Description
`clipId`	Yes	list_clips Session ID or supported list_arrangement_clips ID.
`trackId`	Yes	ID from list_tracks.
`feelBars`	No	Aggregate selected onset offsets and strengths over a repeating one-to-eight-bar clip-meter cycle; grid must divide a bar.
`gridBeats`	Yes	Positive beat-grid spacing, e.g. 0.5 for eighth notes.
`channelIndex`	No	Zero-based source channel; defaults to zero.
`startSeconds`	No	Source window start.
`durationSeconds`	No	Source window duration; defaults to 10 seconds.
`includeMusicalRoles`	No	Label each nearest grid slot by clip-meter bar and pulse role; requires a grid that divides one bar.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv0.3.1Oct 23, 2026

changedInput schema / properties / clipId / description

Previous value: -"Session ID from list_clips; Arrangement ID from list_arrangement_clips where supported."New value: +"list_clips Session ID or supported list_arrangement_clips ID."

removedOutput schema / additionalProperties
```
Removed value: -true
```

addedOutput schema / anyOf

Added value: +[
+  {
+    "properties": {
+      "actions": {
+        "items": {
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "candidateCount": {
+        "type": "integer"
+      },
+      "clipId": {
+        "type": "string"
+      },
+      "gridAlignment": {
+        "items": {
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "gridBeats": {
+        "type": "number"
+      },
+      "nativeConversion": {
+        "const": true
+      },
+      "sourcePath": {
+        "type": "string"
+      },
+      "sourceWindow": {
+        "type": "object"
+      },
+      "stateVersion": {
+        "minimum": 1,
+        "type": "integer"
+      },
+      "trackId": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "stateVersion",
+      "trackId",
+      "clipId",
+      "gridBeats",
+      "nativeConversion",
+      "sourcePath",
+      "sourceWindow",
+      "candidateCount",
+      "gridAlignment",
+      "actions"
+    ],
+    "type": "object"
+  },
+  {
+    "properties": {
+      "error": {
+        "properties": {
+          "message": {
+            "type": "string"
+          },
+          "outcome": {
+            "enum": [
+              "unknown",
+              "not_executed"
+            ]
+          }
+        },
+        "required": [
+          "message",
+          "outcome"
+        ],
+        "type": "object"
+      }
+    },
+    "required": [
+      "error"
+    ],
+    "type": "object"
+  }
+]

Changed3 schema fields changedv0.3.0Oct 19, 2026

changedInput schema / properties / clipId / description

Previous value: -"Stable clip ID: track-N:clip-M from list_clips, or track-N:arrangement-clip-M from list_arrangement_clips for tools that support Arrangement clips."New value: +"Session ID from list_clips; Arrangement ID from list_arrangement_clips where supported."

changedInput schema / properties / trackId / description

Previous value: -"Stable track ID returned by list_tracks."New value: +"ID from list_tracks."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "additionalProperties": true,
+  "type": "object"
+}

Changed2 schema fields changedv0.2.0Sep 30, 2026

addedInput schema / properties / feelBars

Added value: +{
+  "description": "Aggregate selected onset offsets and strengths over a repeating one-to-eight-bar clip-meter cycle; grid must divide a bar.",
+  "maximum": 8,
+  "minimum": 1,
+  "type": "integer"
+}

addedInput schema / properties / includeMusicalRoles

Added value: +{
+  "description": "Label each nearest grid slot by clip-meter bar and pulse role; requires a grid that divides one bar.",
+  "type": "boolean"
+}

First observedv0.1.0Sep 23, 2026

TDQS

A4.2/5.0

Behavior5/5

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

Annotations already declare read-only, idempotent and non-destructive, but the description adds substantial behavioral context beyond them: signed offsets and one-hop detector resolution reporting, suppression of actions inside that resolution or competing with a closer onset, meter-derived role labeling, and the heuristic/no-audible-validation caveat. This is exactly the kind of disclosure that lets an agent predict output trustworthiness.

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?

Purpose is front-loaded in the first sentence and each subsequent clause carries distinct information (suppression rules, roles, feel aggregation, caveats). It is dense and semicolon-heavy, which slightly taxes parsing, but there is little redundancy.

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?

With an output schema present, the description need not explain return shapes, and it still covers scope, suppression behavior, optional role/feel semantics and validation limits. The only meaningful gap is that it does not identify the companion tool that applies the proposed markers after dry-run review.

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 would be 3, but the description genuinely extends semantics: feelBars is described as aggregating one to eight bars of selected onset timing and strength by grid slot (and explicitly not Groove Pool baking), and includeMusicalRoles as labeling bars, downbeats, quarter pulses and half-beat upbeats from the clip meter. That adds meaning beyond the schema text.

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?

The definition opens with a specific verb and resource pair: analyze bounded source-audio onsets and propose review-only marker actions toward a beat grid. The 'review-only/propose' framing implicitly separates it from applying tools like add_audio_warp_marker or quantize_audio_clip. However, it never names those siblings, so the differentiation is inferential rather than explicit.

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 usable exclusions ('this is not native Groove Pool extraction or baking') and a workflow rule ('individually dry-run actions against current state before applying'). It stops short of naming which tool actually applies the proposed markers, leaving the hand-off implicit.

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

Deploy Server