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

With no annotations, the description carries the burden and does it well: it reveals polling semantics, terminal states (succeeded/failed), result/error fields, blocking behavior up to wait seconds, and early return on completion. Minor omission: no mention of authentication, rate limits, or behavior for unknown ids, but core runtime behavior is transparent.

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?

Three dense sentences with no filler: action, workflow, and polling strategy are each front-loaded in their sentence. Every clause earns its place, and the parenthetical limits are efficient.

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?

Despite no output schema or annotations, the description explains the full call contract: when to poll, what statuses indicate completion, how to read result/error, and how long a wait may block. For a simple two-parameter polling tool, nothing essential is missing.

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 a baseline of 3 applies, but the description adds real value: it ties id to the id returned by generation calls and explains the wait parameter's long-polling effect and default return behavior. This exceeds the schema's bare parameter definitions.

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 specific verb+resource pair, 'Poll the status of a generation job', and explains the job lifecycle with {id, status}. This clearly differentiates it from sibling tools like cancelApiJob and listApiJobs, which deal with cancellation and listing rather than status polling.

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 when to call this tool: after any generation tool returns {id, status}, poll until terminal. It also gives polling cadence and long-poll guidance. It does not explicitly contrast with siblings (e.g., when to prefer listApiJobs or cancelApiJob), but the intended usage is unmistakable.

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