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

Goes well past the annotations: pricing (3 credits per kept minute, +4 with burnCaptions), that billing is on kept duration, exactly what gets cut and with what defaults, how cuts are joined (audio fade so joins do not click), and the full output shape. The annotations only cover safety/idempotency, so this added context is doing real work.

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?

Dense but nearly every clause carries operational information; nothing is filler. The ordering is slightly off — the actual purpose sentence arrives third, after the alias and the pricing paragraph — so a scanning agent meets cost before function.

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 24-parameter, no-output-schema mutation with an open-world job submission, the description covers the missing pieces an agent needs: the transcript prerequisite, the exact stats returned, cost model, and the optionality of the caption burn. No output schema is a gap the description closes inline.

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?

At 63% schema coverage the description compensates well, defining the semantics that the schema does not: fillerMode 'clear' vs 'aggressive' word lists, fillers/keepFillers/removeFillers interaction, detectSilences being an ffmpeg silencedetect pass inside word timings, and the burnCaptions style cluster. Several of the 24 parameters (maxCredits, highlightWords, faceAvoid, styleOverrides, quoteOnly) are left to the schema, and some defaults it repeats verbatim from schema fields.

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+resource (removes silences and filler words from a talking video) and immediately anchors it as an alias of remove_silences, then names the return artifacts. The burn_captions renderer cross-reference disambiguates the caption-burn path from the sibling burn_captions tool.

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?

Explicitly states the prerequisite (needs a transcript via transcriptionJobId from transcribe or caption_video, or subtitles), and names when the caption-burn branch routes through the same renderer as burn_captions. It does not, however, say when to prefer trim over remove_silences, or when to use quoteOnly/preview instead of starting the job.

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