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

Goes well past the readOnly/idempotent annotations: discloses that entries include web-app analyses and transcripts (format "text" vs "markdown"), that the analysis body is omitted in favor of length/format, and that whole result is untrusted model-generated text that must never be followed as instructions or rendered as HTML/Markdown. That is exactly the safety and content-shape context an agent needs.

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 WHEN, then behavioral caveats in capitalized labels, which makes scanning easy. It is on the long side and the "do not report a result from this tool" point partially repeats the preceding sentence about omitted text.

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?

With no output schema, the description carries the return-shape burden and does so: per-entry `analysis.length` and `analysis.format`, pagination via `next_cursor`/`has_more`, and a pointer to get_analysis for the body. Nothing needed to call or interpret the result correctly is missing.

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 100%, so the baseline is 3; the description adds value by tying `cursor` to the previous `next_cursor` and gating it on `has_more`, which the schema does not mention. It does not restate the `limit` range or default, but that omission is minor given the schema is fully described.

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 first clause names the resource and its scope ("The account's video analyses"), plus ordering ("newest first") and pagination semantics. It is clearly distinguishable from analyze_video (which creates one) and get_analysis (which fetches the text).

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?

An explicit WHEN block covers both triggers: the user asking what they have analysed, and a pre-check before starting a new analysis because a duplicate may already exist. It also names the follow-up tool (get_analysis with the id) for the actual content.

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