remove_clip_groove

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

The description discloses the critical behavioral trait that the tool does not actually work due to an Ableton API limitation. This goes beyond any annotations (none provided) and is essential for the agent to avoid invoking a non-functional tool. It also explains the workaround, adding significant value.

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 well-structured with a concise statement, an important note, and a clear args list. Every sentence serves a purpose—no fluff—making it efficient and easy to parse.

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 simple tool with two integer parameters, the description covers everything needed: purpose, limitation, alternative, and parameter meanings. The presence of an output schema further reduces the need to explain return values. The description is complete and actionably informative.

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 description includes an Args section explaining each parameter: track_index is 'Zero-based index of the track containing the clip' and clip_index is 'Zero-based index of the clip slot containing the clip.' Since the schema has no per-parameter descriptions (0% coverage), this fully compensates and provides necessary context.

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 tool's intended action: 'Remove the groove assignment from a clip.' It uses a specific verb and resource, and is distinct from sibling tools like set_clip_groove and set_groove_property by focusing on removal.

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 explicitly provides usage guidance by warning that the tool has a known API limitation and recommending a concrete alternative: 'Consider setting groove properties to 0 instead (use set_groove_property...)' This clearly tells the agent when not to use this tool and what to use instead.

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