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

Annotations already declare readOnly/destructive/openWorld=false, and the description adds substantial context beyond them: ordering (newest first), default limit 40, offset paging semantics, what status reports per job phase (stage, queuePosition, estimatedWaitSeconds, estimatedRemainingSeconds), and what returned artifacts look like (image attachment, AMZ Vault download link). It also discloses BETA status, availability, and per-tier export quotas, which an agent needs before promising an export.

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 the resource and the action enumeration, then parameters, then return behavior, then beta/quota caveats. It is dense and parenthesis-heavy with some redundancy (the beta date and quota sentence is long), but nearly every clause carries information an agent needs.

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?

No output schema exists, and the description compensates by describing what status and download actually return, including the queued/running wait-time fields and the artifact/link behavior. The one gap is deferring the exact per-action input schema to a separate video_guide call, which forces an extra hop before first use.

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 carry the full burden and it does: projectId, state, limit (with default 40), offset (older pages), jobId, includeSnapshot, and the meaning of each action enum value are all explained. Every one of the seven parameters has stated semantics that the bare schema lacks.

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 set and resource: Video Director render jobs with actions list, status and download. It is immediately distinguishable from siblings such as video_render (which presumably kicks off a render) and video_producer_status, because the description frames this tool as the job-inspection and download surface.

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?

Per-action guidance is explicit: use list with optional projectId/state for browsing, status with jobId for progress, download with jobId for retrieval, and includeSnapshot=true when the frozen project is wanted. It also routes the agent to video_guide first for the catalog and exact per-action schemas, but stops short of stating when to prefer video_render or video_producer_status instead.

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