Check a Google Flow Job

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

Annotations declare readOnlyHint=false, idempotentHint=true, openWorldHint=true and destructiveHint=false; the description adds the key missing context for why this poll is not read-only — it 'safely finalizes any download already authorized by the original request' — plus the idempotent polling expectation. It does not cover failure modes, rate limits, or how waitSeconds affects behavior, so it stops short of a 5.

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?

Four short sentences, front-loaded with the routing rule and zero filler. The 'safely finalizes any download' sentence is slightly ambiguous about whether it retrieves content, which slightly muddies otherwise tight phrasing.

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?

With only two parameters and no output schema, the description carries more return-value burden, and it does name the terminal states ('completed or failed'). It stops short of describing the status response shape or what intermediate states exist, but for a polling tool this is close to complete.

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 100%: jobId and waitSeconds are both fully documented in the schema, including format, defaults, and bounds. The description reinforces the job ID's origin ('jobs returned by a Flow generation tool') but adds no syntax or format detail beyond what the schema already provides, so the baseline 3 applies.

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 states a specific verb and resource (check/poll a job's status) and scopes it as 'the exclusive status path for jobs returned by a Flow generation tool.' It clearly separates this tool from the generation siblings (flow_generate_video/flow_generate_image) and from generic inspection tools, so an agent can distinguish it without opening a schema.

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?

Explicit when-to-use ('Poll the SAME job ID until completed or failed'), explicit when-not ('never resubmit generation'), and an explicit negative alternative ('Never inspect Flow with generic browser/computer-use tools'). This covers the main failure modes an agent would otherwise fall into.

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