remove_notes_from_clip

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

No annotations exist, so the description must carry the full burden. It explains default behavior and parameter effects but omits crucial details: whether the operation is destructive, requires specific permissions, affects undo history, or has side effects like clearing undo steps. The description is minimal for a mutating 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 extremely concise: a single sentence for purpose followed by a parameter list. Every line adds value, and the default behaviors are efficiently communicated. No redundancy or unnecessary text.

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?

Given no output schema, the description does not mention return values or confirmation. It also omits error handling (e.g., invalid track or clip indices) and does not clarify if the operation is permanent or undoable. For a simple removal tool, the missing context is acceptable but not fully complete.

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?

The input schema has 0% description coverage (no per-parameter descriptions). The description compensates by listing all 6 parameters, clarifying their roles (e.g., 'from_time: Start time in beats'), and explaining defaults. However, it could better clarify the relationship between time_span and from_time, and pitch_span and from_pitch.

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 clearly states the action ('Remove MIDI notes from a clip') and specifies the scope ('within a specified range'). This distinguishes it from sibling tools like 'add_notes_to_clip' and 'get_clip_notes', which have opposite or different purposes.

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 default behavior (remove all notes) but does not explicitly state when to use this tool versus alternatives (e.g., 'quantize_clip' for editing, 'delete_clip' for entire clip removal). No guidance on when not to use it is provided.

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