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

Adds substantive behavior the annotations cannot express: a built-in fallback that cuts only quiet gaps, keeps sounded ones, and can be overridden via allow_nonquiet. Annotations only declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, so this guardrail disclosure is real added value. The phrase 'the pass would be substantially destructive' sits in tension with destructiveHint=false (though it describes the aggressiveness of the edit, not irreversible data loss), and 'listed' is never explained given there is no output schema.

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 first sentence is front-loaded, precise, and does the main work. The second is a single long conditional clause with nested hedges ('when many detected gaps contain audible material and the pass would be substantially destructive ... unless ... applies') that takes real effort to parse and could be split into two sentences.

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?

Covers the mutation's core semantics and safety fallback for a 4-parameter editing tool with annotations but no output schema. It leaves out the prerequisite of running detection first, whether the cut is reversible, and what 'listed' means for the caller's result, all of which an agent would need before invoking it confidently.

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 25% (only project_id documented), but the description compensates by conveying the meaning of all three remaining parameters: a duration threshold (min_silence_s), breathing-room padding (padding_s), and the 'explicit nonquiet override' (allow_nonquiet). It still omits units, defaults, and explicit name-to-concept mapping, so an agent must infer the binding.

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?

Names a concrete verb and object ('Removes detected pauses above a duration threshold') plus the preservation behavior ('retaining breathing-room padding and aligning speech boundaries'), which clearly separates it from the detection sibling find_silences. It stops short of naming any counterpart explicitly, so the contrast is inferred rather than stated.

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 premise 'detected pauses' implies find_silences must run first, but no prerequisite, ordering, or when-not condition is stated. The second sentence governs how the cut behaves, not when to choose this tool over cut_range or cut_output_range, so usage is implied rather than guided.

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