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

Goes far beyond the annotations: discloses the cost model (free review and waiting, charge only on approve at 4 credits/min, same as burn_captions), link constraints (private, up to 7 days, no login, scoped to one video), the reviewer's capabilities (edit text/timing, approve/reject with note, add glossary terms), and event semantics (review.approved/review.rejected/review.expired delivered once each, plus job.succeeded). Nothing here contradicts readOnlyHint=false / destructiveHint=false.

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?

High information density with no filler — price, trigger, mechanics, and follow-up path are all load-bearing. The one knock is structure: everything is packed into a single run-on paragraph mixing pricing, link properties, and event semantics, so an agent must parse rather than scan.

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 15-parameter, no-output-schema tool that gates a paid, irreversible burn behind a human approval, the description supplies everything needed: required input provenance, the returned reviewUrl, how to await the outcome, and what triggers the charge. No output schema is needed because the return value and event names are spelled out.

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 already 87%, so the schema carries most weight, but the description adds real meaning: transcriptionJobId must be a finished transcribe job, preset/brandPresetId govern the burn after approval, webhookUrl/notifyEmail bind to the named events, and the 7-day link lifetime clarifies expiresInDays. It doesn't touch maxCredits, autoFit, styleOverrides, or highlightWords specifics, which the schema handles well.

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?

Specific verb+resource: it creates a human review gate over captions before a burn, returning a reviewUrl. It explicitly separates itself from burn_captions ('Only on Approve does burn_captions run') and from get_review (polling status), so an agent can pick it without opening any schema.

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?

States the trigger condition ('when the person wants to check the captions before they are burned') with multilingual example phrasings, and names the alternatives: burn_captions for the unconditional path, get_review / webhookUrl / notifyEmail for tracking the outcome. When-to-use and when-to-use-something-else are both explicit.

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