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

Annotations already indicate readOnlyHint=true and destructiveHint=false, and the description reinforces this by saying it returns "safe current status" and does not expose prompts, provider details, or private media. It also adds important behavioral context: accepted/running jobs are not complete, retries have timing requirements, replacements are paid, and refund state should be checked after technical failure.

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 front-loaded with the core use case and then adds dense, operational guidance. Every sentence carries meaningful behavioral or routing information, and there is no filler or repetition beyond what is necessary for safe use.

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 having no output schema, the description explains the important parts of the response: current status, failure/refund state, destinations, and retry instructions. It also covers post-success behavior with present_generation and accounts for Audio jobs. For a single-parameter read-only status tool, this is complete enough for an agent to act correctly.

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?

The schema describes only jobId with min/max length, and schema description coverage is 0%. The description implies that jobId must refer to a known owned generation and mentions ambiguous submission responses, which hints at where the ID comes from. However, it never explicitly states how the jobId is obtained or validated, so the agent must infer the source from context.

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 a specific purpose: follow or recover one known owned generation, including after interruption or ambiguous submission. It also distinguishes the tool from sibling present_generation by explaining when to use that tool instead, and from list_recent_generations by focusing on a known single job.

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 usage rules: use for recovery/polling, wait at least retry.afterSeconds before retrying, stop polling when retry is null, avoid repeated checks, do not resubmit on technical failure, and use present_generation once the job is complete. This is strong, actionable guidance that also warns against common misuse.

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