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

Annotations provide only readOnlyHint=false, so the description has to carry the behavioral load, and it does add real information: the mutation is bulk (every clip on every track of a role) unless track_id narrows it, and ducking is applied by role rather than by track. It stops short of stating whether the change is reversible or versioned, which matters for a bulk write.

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?

One sentence, front-loaded with the action and scope, with the two optional effects and their targeting rules packed into tight parentheticals. Nothing extraneous and no repetition of schema content.

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 5-parameter mutation tool with no output schema and minimal annotations, the description covers scope and targeting well but omits what happens when neither volume nor apply_ducking is supplied, and whether the bulk change can be undone. These are realistic gaps an agent would want resolved before calling a write tool against many clips.

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 80%, so the baseline is 3; the description goes slightly beyond by clarifying the interaction between the parameters — volume and ducking are independent ('and/or'), and apply_ducking needs no track_id while volume targeting is governed by track_id. That resolves ambiguity the schema leaves implicit about whether ducking is scoped to the selected track.

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 gives a specific verb and resource ('Adjust an audio role's mix') and enumerates the two effects precisely: per-clip volume and ducking. It partly differentiates from siblings by noting ducking works 'BY ROLE — no track ids needed', which is the key contrast with a track-level ducking tool, but it never names the alternative sibling outright.

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?

Usage is implied rather than stated: the 'and/or' wording makes clear the two operations can be combined or issued separately, and the parenthetical explains which one needs track_id. There is no explicit when-to-use/when-not guidance and no reference to competing tools such as studio.set_ducking or studio.enhance_audio.

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