get_job

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

Since no annotations are provided, the description must disclose behavioral traits. It does so by explaining the long-polling mechanism, the return of finished asset only when COMPLETE, and the immediate return of current state when wait_seconds=0. This adds useful context beyond a simple 'fetch state'. However, it does not mention permission requirements, rate limits, or error handling, which would be valuable.

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 two sentences, highly efficient, and front-loaded. Every word adds value: it names the action, the resource, the optional polling, and the result condition. No extraneous information.

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 tool is simple (2 parameters, no output schema, no annotations). The description covers the core polling behavior adequately, but lacks details about the structure of the returned state, possible statuses besides COMPLETE, and error scenarios. For a straightforward fetch tool, it is minimally complete but leaves some information for the agent to infer.

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 input schema has 50% description coverage (wait_seconds is described in schema, generation_id is not). The tool description repeats the wait_seconds behavior but adds nothing new about generation_id, which remains undocumented. With moderate coverage, the description does not fully compensate, so a score of 3 is appropriate.

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 'Fetch a generation's current state' with a specific verb and resource. It distinguishes from sibling tools like generate_image, generate_video, and get_media by focusing on polling job status rather than creation or media fetching. However, it could be more explicit about differentiation from similar get_media or list_media tools.

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 explains the optional long-polling and the default behavior when wait_seconds=0, but does not provide guidance on when to use this tool vs alternatives like get_media (for finished assets) or list_media (for browsing). No when-not-to-use or alternative tool references are given, though the context of polling generation state is clear.

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