Live Maestro

Overview Schema Source Related Servers Discussions Admin

read_automation

Read-onlyIdempotent

Sample a clip envelope into evenly spaced values to inspect how a parameter changes over time. Returns sampled values, beat range, and whether an envelope exists.

Instructions

Sample a clip envelope into a list of values and report what it found.

Reads the curve by evaluating it at ``points`` positions, so the answer is a
sampling of the envelope rather than the breakpoints that define it.

Returns:
    Dictionary with the sampled values, the beat range they cover, the value
    range they span, and flags saying whether an envelope exists at all.

Note:
    Automation lives in Session clips, so an Arrangement clip has none to read.
    als_read is the way to see breakpoints in a saved project instead.

    Use write_automation to lay a curve down and clear_automation to remove one.
    A flat result with an envelope flag of false means nothing is automated on
    that parameter, which is not the same as an envelope holding the parameter's
    current value.

Input Schema

TableJSON Schema

Name	Required	Description
`end`	No	Last beat to sample, clip-local. Omit to sample to the end of the clip.
`path`	No	LOM path to a Session clip, song.tracks[N].clip_slots[M] with or without a trailing .clip, as an alternative to track and slot. A song.tracks[N].arrangement_clips[i] path is refused with code region_not_addressable.
`slot`	No	Clip slot index in track.clip_slots, counted from 0, which is the scene the clip sits in. Give track and slot, or give path instead. These are Session coordinates; an Arrangement clip has none.
`start`	No	First beat to sample, clip-local, where 0 is the clip start. Omit to start just past beat 0, which steps over the guard that keeps a sample off the envelope edge.
`track`	No	Session track index in song.tracks, counted from 0. Give track and slot, or give path instead. These are Session coordinates; an Arrangement clip has none.
`points`	No	How many evenly spaced samples to take across the range. Clamped to 2..512. This is the resolution of the answer, not of the stored envelope, which keeps whatever breakpoints it was written with.
`parameter`	Yes	LOM path to the DeviceParameter the envelope belongs to, e.g. 'song.tracks[0].mixer_device.volume' for track volume or 'song.tracks[0].devices[1].parameters[3]' for a device knob.

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed10 schema fields changedSep 24, 2026

addedInput schema / properties / path

Added value: +{
+  "default": "",
+  "description": "LOM path to a Session clip, song.tracks[N].clip_slots[M] with or without a trailing .clip, as an alternative to track and slot. A song.tracks[N].arrangement_clips[i] path is refused with code region_not_addressable.",
+  "title": "Path",
+  "type": "string"
+}

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, which is the scene the clip sits in. Give track and slot, or give path instead. These are Session coordinates; an Arrangement clip has none."

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

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: +"Session track index in song.tracks, counted from 0. Give track and slot, or give path instead. These are Session coordinates; an Arrangement clip has none."

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

changedInput schema / required

Previous value: -[
-  "track",
-  "slot",
-  "parameter"
-]New value: +[
+  "parameter"
+]

Changed6 schema fields changedv0.1.1Sep 7, 2026

addedInput schema / properties / end / description

Added value: +"Last beat to sample, clip-local. Omit to sample to the end of the clip."

addedInput schema / properties / parameter / description

Added value: +"LOM path to the DeviceParameter the envelope belongs to, e.g. 'song.tracks[0].mixer_device.volume' for track volume or 'song.tracks[0].devices[1].parameters[3]' for a device knob."

addedInput schema / properties / points / description

Added value: +"How many evenly spaced samples to take across the range. Clamped to 2..512. This is the resolution of the answer, not of the stored envelope, which keeps whatever breakpoints it was written with."

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 / start / description

Added value: +"First beat to sample, clip-local, where 0 is the clip start. Omit to start just past beat 0, which steps over the guard that keeps a sample off the envelope edge."

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?

The description goes beyond the readOnly/idempotent annotations by explaining that the result is a sampling at points positions rather than breakpoints, and by clarifying the semantic distinction between 'nothing is automated' and 'an envelope holding the parameter's current value.' It also discloses the return shape: sampled values, beat range, value range, and existence flags. No contradiction with annotations.

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 front-loaded with the core action and then uses clearly labeled 'Returns' and 'Note' sections for supplementary detail. Every sentence carries information: the sampling distinction, the return dictionary, the Session-vs-Arrangement caveat, and the alternative tools. It is longer than the simplest descriptions, but it is appropriately sized for a tool with 7 parameters and meaningful edge cases.

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?

The description is complete for the tool's complexity: it explains what the tool returns, how it differs from related tools, the Session-clip requirement, and the subtle false-flag meaning. The input schema fully documents parameters, and an output schema exists, so the prose fills the remaining behavioral and contextual gaps. Nothing an agent needs to invoke this correctly 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, but the description adds tool-level meaning that clarifies parameters: 'evaluating it at points positions' explains the role of the points parameter, and 'sampling of the envelope rather than the breakpoints' frames what all parameters collectively produce. It doesn't re-document each parameter, but it adds useful conceptual context beyond the schema.

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 specific verb and resource: 'Sample a clip envelope into a list of values and report what it found.' It immediately distinguishes itself from related tools by stating that it returns a sampling of the envelope, not the breakpoints, which differentiates it from als_read. This makes the tool's purpose unmistakable.

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?

The description explicitly says when to use this tool versus alternatives: 'als_read is the way to see breakpoints in a saved project instead,' and 'Use write_automation to lay a curve down and clear_automation to remove one.' It also provides a key contextual constraint: automation lives in Session clips, so Arrangement clips have none to read. This is model-level guidance that leaves little to inference.

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