legato_midi_notes

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

With no annotations, the description fully carries the behavioral burden. It specifies that only note ends move, that starts are never touched, that 'connect' never shortens and respects max_gap_beats with gaps_preserved, that the last note is left alone, and that out-of-bounds notes are kept and reported. This is thorough for a mutation tool.

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?

The description is front-loaded with the core purpose and then structured into behavioral detail, Args, and Returns. It is generally efficient, though the mode definitions in the opening paragraph are repeated in the Args section, adding minor redundancy.

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?

For a complex 13-parameter mutation tool with no annotations and no output schema, the description covers the main behavior and return shape but fails to explain most parameters, including how to target notes by channel, pitch, beat range, or fields. An agent would lack crucial information to invoke the tool correctly beyond the core mode settings.

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%, so the description must explain all 13 parameters, but it documents only mode, voice, max_gap_beats, and length_beats. Key filtering and targeting parameters such as track_index, item_index, fields, channel, end_beat, pitch_low, pitch_high, start_beat, and return_notes remain unexplained, leaving significant gaps.

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?

The description states a specific verb and resource: closing gaps in a MIDI line (legato) or setting every note to one length. It is clear and unique among siblings, but it does not explicitly differentiate itself from related MIDI editing tools like quantize_midi_notes or remove_overlapping_midi_notes.

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 clearly explains when to use each mode: 'connect' for legato extension and 'fixed' for uniform lengths, including detailed behavioral conditions. However, it offers no guidance on when to choose this tool over sibling tools such as quantize_midi_notes or humanize_midi_notes.

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