seeany_wait_generation

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

Annotations already declare the operation read-only and non-destructive. The description adds useful behavioral context by indicating that the tool blocks until a terminal state or timeout. It does not, however, explain what constitutes a terminal state, whether it returns partial status updates, or what happens on timeout beyond the parameter constraints.

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, clear, front-loaded sentence. It wastes no words and conveys the core action, target resource, and termination condition efficiently.

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 simple polling tool, the essentials are present, but there is no output schema and the description does not mention what the response contains or what terminal state values might look like. This is a noticeable gap, though the tool is simple enough that an agent could still invoke it correctly with the given schema and annotations.

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 carries the burden of explaining parameters. It indirectly clarifies timeout_seconds by referencing the timeout expiring, and job_id is implied to identify the generation task. The parameter names are fairly self-explanatory, but the description does not explicitly define job_id's origin or the exact effect of timeout_seconds beyond the schema constraints.

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 clearly states the verb 'Poll', the resource 'SeeAny generation task', and the exit condition 'until it reaches a terminal state or the timeout expires.' This sufficiently conveys the tool's purpose and implicitly distinguishes it from a one-shot status check like seeany_get_generation, though it does not explicitly name the sibling alternative.

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 implies when to use the tool: when you want to wait for a generation task to finish rather than just fetch its current state. However, it does not explicitly state when not to use it or point to seeany_get_generation for single status checks, leaving the choice partly to inference.

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