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

Annotations already establish read-only, idempotent, non-destructive, closed-world behavior. The description adds useful specifics beyond that: a 40-second wait cap, finished video.url/downloadUrl returns, nonterminal pending responses with exact nextCall, current access checks, and no generation/approval/credit change.

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?

The description is three tightly packed sentences with no filler. It front-loads the wait behavior and return values, then adds access and side-effect clarifications.

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 wait-and-poll tool with an output schema and rich annotations, the description covers timeout behavior, return shape, pending follow-up, access checks, and side effects. The remaining gap is parameter semantics and explicit routing versus sibling status/result tools.

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 0%, so the description must compensate for parameter meaning. It vaguely refers to the 'original Motion operation', which hints at operationId, but it never explains projectId or operationId semantics, formats, or how the agent should obtain them.

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: waits for the original Motion operation and returns a finished video URL or pending response. It clearly distinguishes itself from mutation tools such as generation, approval, and credit-changing siblings, but does not explicitly distinguish itself from sibling status/result polling tools.

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?

The description implies usage after a Motion operation exists and tells the agent to follow the exact nextCall when pending. However, it does not explicitly say when to use this tool versus studio_motion_status, studio_motion_result, or other wait tools, leaving alternatives to inference.

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