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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds behavior they cannot express: the returned frame reflects the last render, may be stale after edits, and the response itself indicates staleness. It also discloses that calls are free, which matters for agent retry behavior.

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?

Front-loaded with purpose, then parameters, then timing caveat, then exclusions — good ordering. A few parentheticals and repeated references to waiting on job_status make it denser than strictly necessary, but every sentence contributes information.

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 two-parameter read tool with an output schema, this covers everything an agent needs: input provenance, timing prerequisites, staleness behavior, cost, and sibling routing. Return format details are correctly omitted since an output schema exists.

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?

With 0% schema description coverage, the description carries the full load and does: clip_id is sourced from list_clips, at_seconds is measured into the finished clip (not source media), defaults to 1, and behaves differently for photos ("a photo shows whole"). Only the photo phrasing is slightly cryptic, but the key semantics are covered.

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 concrete verb and resource ("Returns a still image of clip_id ... at at_seconds") and anchors it to real user intent with quoted example requests ("show me the captions", "what did that effect do"). It also explicitly distances itself from three siblings: show_clips, get_download_link, and any mutating 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?

Gives an explicit when-to-use trigger, a timing rule (wait for job_status to say done after style_clip, add_to_clip, translate_captions, or edit_clip), and a "Not for:" list naming the correct alternatives for playback and file download. Nothing is left to inference.

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