commit_groove

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

With no annotations, the description carries the full burden for behavioral disclosure. It does state that the action makes quantization permanent, which implies a mutating operation, but it does not explain what exactly changes (e.g., note timing/velocity), whether it overwrites existing quantization, if it is reversible via `undo`, or any failure conditions.

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 brief and front-loads the core purpose in the first sentence. The parameter lines are somewhat redundant with the schema titles, but they do not bloat the description; it remains appropriately sized for a simple two-parameter tool.

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 that this is a mutation-like tool with no annotations, no output schema, and only terse parameter listings, the description lacks essential context: relationship to `apply_groove`, what 'permanent' means for the clip data, and whether any undo mechanism is implied. The two simple parameters limit complexity, but the missing workflow and side-effect context make this incomplete for reliable agent use.

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%, so the description must compensate for missing parameter documentation. However, it only restates 'track_index' and 'clip_index' as 'The index of the track' and 'The index of the clip slot', adding no non-obvious semantics like zero-based indexing, valid ranges, or how the track/clip is selected.

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 uses a specific verb+resource: 'Commit groove quantization to clip notes' and adds '(make it permanent)' which distinguishes it from the sibling `apply_groove` by implying a permanent vs. temporary effect. However, it doesn't explicitly name the alternative tool, so it misses the strongest form of differentiation.

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?

No guidance is given about when to use this tool versus alternatives like `apply_groove` or `get_groove_pool`. The phrase 'make it permanent' implies a workflow context (applying a groove first, then committing), but this is not explicit, and no exclusions or prerequisites are stated.

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