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

Annotations declare destructiveHint=true, which is a strong signal that this operation has side effects (billing, resource creation). The description adds 'paid' and 'retain the video asset ID' but doesn't disclose the destructive nature, cost implications, or that it consumes credits. It also doesn't mention that the task is async and requires polling, which is critical behavioral context. The description doesn't contradict annotations, but it fails to add meaningful behavioral disclosure beyond what annotations already say.

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 a single sentence that front-loads the key action ('Start a paid video-only task') and then gives a compact workflow. It's efficient with no wasted words. It could be slightly more structured (e.g., separating the workflow steps), but it's appropriately sized for the complexity.

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?

The description covers the essential workflow (start, poll, retain asset ID) and mentions the payment requirement. However, it doesn't mention that the operation is destructive (per annotations), doesn't explain the async nature explicitly, and doesn't clarify the relationship between quote_id and max_credits. Given the output schema exists and the schema is rich, the description is adequate but has clear gaps around cost and side effects.

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 50%, and the description adds context for quote_id/max_credits ('approved', 'paid') and idempotency_key ('Save the task ID'). However, the description doesn't explain the 'request' parameter structure or the relationship between quote_id and max_credits (mutually exclusive? both?). The schema already documents most parameters well, so the description adds marginal value but doesn't fully compensate for the 50% coverage gap.

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 states a specific verb ('Start'), a resource ('paid video-only task'), and the required payment inputs ('approved quote_id or max_credits'). It clearly distinguishes from siblings like get_video_generation and preview_video by focusing on task creation. However, it doesn't explicitly name a sibling alternative, so it loses one point for not differentiating from generate_animation or quote_video_generation.

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 gives clear context: use this when you have an approved quote_id or max_credits, and it tells the agent to save the task ID and poll get_video_generation. It implies this is the creation step in a workflow. It doesn't explicitly state when NOT to use it (e.g., for animation use generate_animation), so it's not a 5.

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