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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered and the description is free to add the operational behavior: that the call reports progress across four lifecycle states plus a stage and an expected wait, which implies a poll-until-ready pattern. It does not say how frequently to poll or whether the call blocks, which is the one behavioral detail an agent would still want.

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?

Two sentences with no filler: the return payload leads and the workflow note follows. The first sentence is telegraphic ('the wait') in a way that takes a beat to parse, which costs a little clarity but keeps the definition short.

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?

There is no output schema, so the description carries the return contract and does so adequately by listing state, stage, wait, id and url. For a one-parameter read tool with readOnly annotations that is nearly complete; only the failure/unknown-id case is unaddressed.

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% and the single parameter is documented in the schema as 'Video id from make_video or make_video_from_my_videos', which the description largely repeats. The description's added value is where that id comes from and where it goes next (create_post), which is workflow context rather than new parameter meaning, so the baseline 3 applies.

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 description names the resource (a video, whether still rendering or finished) and enumerates exactly what it reports: state with its four possible values (queued, running, ready, failed), stage, wait time, and, once ready, video.id and video.url. It also names the producing siblings (make_video, make_video_from_my_videos), so an agent can place it precisely in the pipeline rather than confusing it with get_post or get_shoot.

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?

It gives explicit sequencing guidance — 'Use it after make_video or make_video_from_my_videos' — and states the downstream action, passing video.id to create_post as a media id. What is missing is any exclusion, such as what to do if the id is unknown or whether to re-poll once state is ready, so it stops short of a full when/when-not rule set.

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