set_clip_volume

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

No annotations are provided, so the description carries the full burden. It does disclose the value scale (0 = unchanged, -6 = half as loud) and the ceiling of +15, which is real behavioral context, but it says nothing about reversibility, undo, permissions, what happens to existing keyframes, or the response. For an unannotated mutation tool that is a meaningful gap.

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 clauses, front-loaded with the core action and its units, followed immediately by the mode switch. No filler, and every clause carries information an agent needs.

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?

The core semantics are covered, but for a 4-parameter mutation with no annotations and no output schema, the description omits whether existing keyframes/automation are overwritten by a static set, whether the change is undoable, and what is returned. Adequate but with clear gaps.

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 coverage is 75%, and the one undocumented parameter, volumeDb, is fully explained in the description (dB scale, reference points, max +15). The description also adds semantics the schema lacks for time: supplying it converts the call into a keyframe write rather than a static set. It adds value beyond the schema.

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 an audio clip's volume, with the unit (dB) named up front. It differentiates the keyframe mode from the plain set, but never mentions the closest siblings (get_clip_volume, set_clip_channel_volume, fade_clip_volume, set_track_volume), so an agent must infer the clip-versus-track/pan distinction.

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?

"Give time to set a keyframe instead" is genuine routing guidance, but only between the two modes of this same tool. There is no guidance on choosing between this and sibling volume tools, nor any prerequisite context (for example, that the clip must exist or be audio, and that the indices come from get_timeline_clips).

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