Read MIDI notes from a Session clip in Ableton Live by track and clip index; returns note data, an empty list for empty slots, or WRONG_TYPE for audio clips.
Read MIDI notes from one Session clip.
Side effects: none.
Example: get_clip_notes(0, 1) reads slot one on track zero.
Edge cases: audio clips return WRONG_TYPE and empty slots return an empty list.
| Name | Required | Description | Default |
|---|---|---|---|
| clip_index | Yes | ||
| track_index | Yes |
Changes observed during successful MCP inspections.
v0.7.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does well: it states 'Side effects: none,' documents an example invocation, and specifies concrete edge-case behavior (WRONG_TYPE for audio clips, empty list for empty slots). It doesn't state auth/permission needs or whether the operation requires the clip to be loaded/armed, but covers the key failure modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three compact lines: purpose, side effects, example, edge cases. No filler, front-loaded with the core purpose, and structured for fast scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description reasonably fills the gap by naming return behavior (MIDI notes, empty list, WRONG_TYPE). It could specify return shape (note fields: pitch, velocity, timing) to fully substitute for a missing output schema, but overall it is adequately complete for a simple two-param read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% with no param descriptions, so the description must compensate. The example 'get_clip_notes(0, 1) reads slot one on track zero' clarifies that the first arg is track_index and the second is clip_index, which is useful. It doesn't explain index origin (0-based confirmed by example) or valid ranges, and relies on a single example.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource+scope: 'Read MIDI notes from one Session clip.' It distinguishes itself from siblings like get_clip_info, get_clip_summary, and get_clip_automation by naming the exact return (MIDI notes) and the exact container (one Session clip).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the usage context (reading notes from a single clip) but doesn't state when to prefer this over get_clip_info, get_clip_summary, or diagnose_midi_clip. No explicit when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.