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

Adds substantial context beyond the annotations: the first call generates the frames and can take a few seconds (explaining why readOnlyHint is false, without contradicting idempotentHint since repeats reuse the same result), previews are 640 px while the final cover is re-rendered at full size, and unreadable videos (>=100 MB, >10 min, odd format) fall back to sample_times_ms until a person opens the app's cover picker.

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?

Single dense paragraph, front-loaded with what the tool returns before moving to usage and platform constraints. Every clause carries decision-relevant information (scoring criteria, platform matrix, latency/fallback), though the platform matrix is arguably about the consumer of the result and makes the paragraph heavy.

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?

Given an output schema exists, return values need no further explanation, yet the description still covers scoring dimensions, downstream usage, platform applicability, first-call latency, and the degraded path for unreadable videos. Nothing needed to call this tool correctly appears to be 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 description coverage is 100% for both parameters, so the baseline is 3. The description clarifies that media_id refers to a video and implies ranking/ordering of results, but says nothing about limit (the only other parameter) beyond what the schema already states.

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 and resource — candidate cover frames of a video, ranked best-first — and immediately enumerates what each candidate contains (media_id, url, offset_ms, score, notes). It is clearly distinguishable from siblings such as make_cover or add_media 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?

Explains the downstream chain concretely (feed a candidate into update_post/create_post as cover_media_id + thumb_offset_ms) and gives platform rules that determine whether the call is worthwhile at all (Stories/X/Threads/Bluesky take none; YouTube images only on long videos). It does not, however, explicitly contrast this tool with the sibling make_cover, which is left as inference.

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