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

The annotations already indicate destructiveHint=true and readOnlyHint=false, so the agent knows this is a mutating operation. The description adds context that it involves spending credits (implied by the advice to review costs before spending credits), and clarifies default behavior (defaults to grok-imagine only when user didn't name a model). This goes beyond annotations by warning about cost implications, though it doesn't explicitly state the exact side effects.

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 sentences, front-loading the core purpose, then providing mapping details and two actionable instructions. Every sentence carries relevant information with no redundancy, making it concise and well structured.

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 tool with six parameters, three enums, and a destructive annotation, the description covers model selection, default behavior, and cost caution. It leaves out details like asynchronous execution or return values, but since there is no output schema and the parameter schema is complete, the description is reasonably complete. It could mention that generation may take time or return a job reference, but that's not critical.

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 each parameter is well documented. The description adds the crucial rule 'Never omit model when the user named one' and clarifies the default fallback, which is not directly in the schema. This gives the agent deeper understanding of model handling beyond the enum values, so it adds value above the schema.

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 action: generating an AI video, and lists the supported model families (Grok Imagine, Seedance, Veo, Kling). It clearly distinguishes from the sibling generate_image by focusing on video, and the verb 'generate' is precise. The mapping details further clarify what the tool does.

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 explicit guidance: call list_models when the user wants to review models and costs before spending credits, and never omit model when the user named one. This directs the agent to the appropriate sibling for cost review and sets a clear rule for model handling, making usage conditions explicit.

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