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

The description discloses the side effect of creating a new child generation record and instructs to poll it with wait_for_generation. It explicitly describes failure modes: 'auth', 'payment_required' (with x402 challenge), or 'failed', matching the generate contract. This goes well beyond the annotations (readOnlyHint false, openWorldHint true, idempotentHint false) by detailing auth and payment requirements, which is valuable for an agent to handle errors appropriately.

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 well-structured with a one-line summary, a workflow context sentence, and clearly labeled Args and Returns sections. It is front-loaded with the primary purpose, and every sentence adds actionable information. No fluff or redundancy; the length is justified by the tool's complexity and the need to explain action types and slot semantics.

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 is complete for an agent to invoke correctly: it explains the prerequisite workflow, all parameters (with required/optional nuance), the return shape (including polling instruction), and error handling. With an output schema present, it still goes beyond by describing the child generation record and the isError contract. No critical information is missing for safe and correct usage.

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%, but the description enriches each parameter with context. For action_type it lists concrete examples (upscale_2x, vary_strong, etc.). It explains parent_image_index as a slot index (0-3) and clarifies when to omit it. For prompt it specifies steering variations or describing motion. It also notes callback_url is 'same as generate,' providing continuity. This adds meaning beyond the schema's terse field descriptions, though some params (callback_url) rely on prior knowledge.

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 opens with a clear, specific verb and resource: 'Run a follow-up action on a completed generation's image.' It distinguishes itself from sibling tools like generate (creates) and wait_for_generation (polls) by focusing on post-generation actions. The reference to available_actions and the list of action types leaves no ambiguity about the tool's scope.

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?

It explicitly states the workflow: 'After generate → wait_for_generation, the response's processing_result.available_actions lists what's possible per slot. Call this tool with one of those action types.' This provides clear context for when to use the tool. It also gives guidance on per-slot vs. global actions (omit parent_image_index for reroll), but does not explicitly contrast with alternatives like calling generate again. Slight gap in explicit exclusion criteria, but context is sufficient.

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