Remove all MIDI notes from a specific item on a track by providing track and item indices. Returns the number of notes deleted to confirm the action.
Delete all MIDI notes from an item.
Returns: Object with count of notes deleted.
| Name | Required | Description | Default |
|---|---|---|---|
| item_index | Yes | ||
| track_index | Yes |
Changes observed during successful MCP inspections.
v1.7.3Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the return value (count of deleted notes) and explicitly states the destructive action ('Delete all'), which aligns with the destructiveHint annotation. Beyond the existing annotation, it provides the return format and confirms the scope. It does not mention reversibility, selection behavior, or other side effects, but the annotation covers the core destructive nature.
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?
Two short sentences with zero waste. The action is front-loaded, and the return information is briefly stated. No redundancy or filler.
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 destructive MIDI operation with two undocumented parameters, the description is insufficient. It lacks parameter explanations and any guidance on when to use this tool over siblings like delete_midi_note. The return count is mentioned, but the overall context for correct invocation is incomplete.
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 description coverage is 0%, and the description provides no explanation for track_index or item_index. It merely references 'an item' without specifying how the parameters map to the item. The burden falls on the description to clarify parameters, and it completely fails to do so.
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 ('Delete') and resource ('all MIDI notes from an item') with clear scope. It distinguishes from single-note deletion (delete_midi_note) and note addition (add_midi_note) by targeting all notes in an item. The name and description align perfectly.
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 implies when to use it: to remove all MIDI notes from an item. However, it does not explicitly compare with alternatives like delete_midi_note (single note) or note editing tools, nor does it state any conditions for use vs. not use. No exclusions or alternative routing are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.