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

Beyond the annotations (which only say this is a non-read-only, non-destructive, closed-world mutation), the description discloses a real behavioral detail: speech is sourced from the detection made at upload, falling back to the transcript, then to audio level. That fallback chain tells the agent the tool works even without captions. It does not say whether existing ducking settings are replaced or whether the operation is reversible, which keeps it short of a 5.

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?

Three compact sentences, front-loaded with the purpose before the fallback detail and the parameter note. No filler, and the parentheticals carry concrete calibration values rather than padding.

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 3-parameter mutation tool with no output schema and only safety annotations, the description covers purpose, triggering mechanism, the key parameter's units, and how to turn it off. Remaining gaps — whether it overwrites prior ducking config and whether the change is undoable — are minor but real for a mutation.

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 only 33% — only projectId is documented in the schema — so the description must compensate, and it largely does for the most important parameter: amount is defined as the music level during speech, given a concrete anchor (0.25 ≈ -12 dB) and null semantics for disabling. trackId is left unexplained, but it is self-evident given the 'music track' framing.

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 names a specific verb and effect — automatically lowering a music track while speech is present — rather than restating the name 'set ducking'. It also distinguishes this from a generic level change by stating the trigger (speech) and the mechanism, so an agent can tell it apart from siblings like level_audio or set_voice_cleanup.

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: an agent can infer 'use this to duck music under dialogue' and 'pass null to disable', which is genuine guidance for the off case. However, no sibling alternatives are named (level_audio, add_music, remove_silences), and there is no explicit when-not guidance, leaving the agent to infer tool selection.

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