ableton-mcp

Overview Schema Source Related Servers Discussions Admin

plan_midi_diatonic_chord_quality

Read-onlyIdempotent

Plan selected MIDI onsets into diatonic, secondary-dominant, parallel-minor borrowed, suspended, added-tone, or altered-dominant voicings using per-onset recipes, modes, inversions, and slash basses.

Instructions

Plan complete selected onsets as scale-native, secondary-dominant, parallel-minor borrowed, suspended, added-tone, or altered-dominant voicings. Supports per-onset functions, recipes, inversions, voicing modes, and explicit scale-degree slash basses.

Input Schema

Name	Required	Description
`mode`	Yes
`clipId`	Yes	list_clips Session ID or supported list_arrangement_clips ID.
`noteIds`	Yes	Unique stable note IDs at complete chord onsets.
`trackId`	Yes	ID from list_tracks.
`chordSize`	No	Exact voicing recipe. Triad, seventh, and ninth stack thirds from Live's scale; suspended, added-tone, and dominant recipes use their named literal intervals, with tensions voiced above the chord.
`chordSizes`	No	One exact voicing recipe for each ordered onset.
`inversions`	No	Optional inversion steps for each ordered onset; zero keeps root position.
`bassDegrees`	No	Optional Live scale degree for one added slash-bass voice below each ordered onset.
`rootDegrees`	Yes	One root degree from Live's current scale for each ordered onset.
`voicingModes`	No	Optional deterministic voicing mode for each ordered onset.
`harmonicFunctions`	No	Optional harmonic function for each ordered onset; secondary-dominant root degrees name tonicized targets.

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": {
+      "clipId": {
+        "type": "string"
+      },
+      "context": {
+        "type": "object"
+      },
+      "plan": {
+        "properties": {
+          "changes": {
+            "items": {
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "newNotes": {
+            "items": {
+              "properties": {
+                "duration": {
+                  "type": "number"
+                },
+                "pitch": {
+                  "maximum": 127,
+                  "minimum": 0,
+                  "type": "integer"
+                },
+                "start": {
+                  "type": "number"
+                },
+                "velocity": {
+                  "maximum": 127,
+                  "minimum": 0,
+                  "type": "integer"
+                }
+              },
+              "required": [
+                "pitch",
+                "start",
+                "duration",
+                "velocity"
+              ],
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "noteIds": {
+            "items": {
+              "type": "integer"
+            },
+            "type": "array"
+          },
+          "notes": {
+            "items": {
+              "properties": {
+                "duration": {
+                  "type": "number"
+                },
+                "pitch": {
+                  "maximum": 127,
+                  "minimum": 0,
+                  "type": "integer"
+                },
+                "start": {
+                  "type": "number"
+                },
+                "velocity": {
+                  "maximum": 127,
+                  "minimum": 0,
+                  "type": "integer"
+                }
+              },
+              "required": [
+                "pitch",
+                "start",
+                "duration",
+                "velocity"
+              ],
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "preservedNotes": {
+            "items": {
+              "type": "object"
+            },
+            "type": "array"
+          }
+        },
+        "required": [],
+        "type": "object"
+      },
+      "stateVersion": {
+        "minimum": 1,
+        "type": "integer"
+      },
+      "trackId": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "stateVersion",
+      "trackId",
+      "clipId",
+      "context",
+      "plan"
+    ],
+    "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"
+}

First observedv0.1.0Sep 23, 2026

TDQS

B3.4/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds some behavioral scope by specifying that it plans complete selected onsets and supports per-onset features, but it does not disclose anything about the returned plan or how it differs behaviorally from the apply sibling beyond the word 'Plan'.

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 definition is two tightly written sentences with no filler. The core planning action and supported voicing categories are front-loaded, followed by a compact list of per-onset capabilities.

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 complex 11-parameter tool with an output schema and rich annotations, the description covers the key voicing categories and optional per-onset features. It is nearly complete, though it could explicitly frame the plan stage relative to the apply tool to remove any ambiguity about whether chords are actually modified.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is high at 91%, so the schema already carries most parameter meaning. The description maps conceptually to several optional parameters (per-onset functions, recipes, inversions, voicing modes, slash basses), but it does not add syntax or format details beyond what the schema provides, so the baseline of 3 is appropriate.

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 description uses a specific verb ('Plan') and resource ('complete selected onsets as ... voicings'), and enumerates the harmonic categories it covers. This makes the tool's purpose clear, though it does not explicitly name the contrasting apply_midi_diatonic_chord_quality sibling to clarify plan-vs-apply boundaries.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description lists capabilities but gives no guidance on when to use this tool versus alternatives such as apply_midi_diatonic_chord_quality or other planning tools. It does not state preconditions, exclusions, or workflow context beyond the implied 'plan' verb.

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

Deploy Server