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

Adds substantial context beyond the annotations: it discloses that the call spends credits, that it is asynchronous ("Returns immediately with a nodeId and status"), and the exact polling contract (until COMPLETED or FAILED). This is consistent with readOnlyHint=false and idempotentHint=false and tells the agent how to handle the response, which the annotations cannot.

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?

Five dense sentences, zero filler, front-loaded with the action and the prerequisite. Each clause carries a distinct operational fact (model source, duration constraint, cost, optional frames, async return) rather than restating the schema.

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 7-parameter credit-spending generation tool with no output schema, the description covers the prerequisite chain, cost risk, optional inputs, and the full async lifecycle including the follow-up tool. An agent has everything needed to invoke it correctly and handle the result.

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 coverage is 100%, so baseline is 3, but the description earns extra by cross-referencing other tools: modelKey comes from list_models, durationSeconds must be one the model supports, and sourceFileIds come from upload_image or the library and act as start/reference frames. resolution and aspectRatio defaults remain schema-only, which is acceptable given the schema already states 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 ("Start generating a NEW video from a text prompt") plus the scope constraint (in a thread). The capitalized NEW and the text-prompt framing distinguish it from edit_video, extend_video, image_to_video, and generate_image without the agent needing to open sibling schemas.

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?

Gives concrete prerequisites and routing: create_thread first, modelKey from list_models, durationSeconds must be model-supported, estimate_cost if unsure, then poll get_generation_status. What's missing is an explicit when-not — e.g. it never says to use image_to_video instead when a single source image drives the clip, which matters given sourceFileIds overlaps with that sibling.

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