set_clip

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

Annotations already declare readOnly=false, idempotent=true, destructive=false, so the safety profile is covered. The description adds genuine value beyond that: patch semantics ('only the ones you pass change') and the return contract ('Returns the clip as get_clip'), plus audio-only scoping for several fields. It stops short of noting auth requirements or what happens on partially valid input.

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?

Front-loads the key semantics (patch behavior, return shape) before the dense parameter reference and ends with a concrete example. Given 25 parameters, the telegram-style format is efficient and every clause carries information, though the run-on single block is slightly hard 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 25-parameter mutation tool with no output schema and no schema descriptions, the description covers patch semantics, return shape, time grammar, and the most error-prone enums/ranges. The remaining undocumented parameters and the absence of any note on failure behavior keep it from 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?

With 0% schema coverage across 25 parameters, the description carries the full load and delivers a lot: time format ('bar.beat.sixteenth', seconds for unwarped audio), signature format, launch_mode enums, launch_quantization values, grid values, groove resolution, gain_db and pitch ranges, and warp_mode enums. It leaves a substantial tail undocumented (name, color, muted, legato, looping, start_marker, end_marker, grid_triplet, velocity_amount, arrangement_clip), keeping it off a 5.

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?

States a specific verb and resource ('Set clip properties') and clarifies patch semantics ('only the ones you pass change'). It links itself to a sibling by stating 'Returns the clip as get_clip', so an agent can distinguish this mutation from the read path, though it doesn't explicitly contrast with set_track or create_clip.

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?

'only the ones you pass change' tells the agent this is a partial-update tool, implying usage context. However there is no explicit when-to-use-vs-alternatives guidance (e.g., set_clip vs create_clip vs set_track) and no stated prerequisites or exclusions.

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