Generate images in Flow

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

With no annotations, the description carries the burden and mostly does: it discloses that the call is long-blocking ('wait until the images finish'), returns media ids, can download as a side effect, and self-aborts on credit cost. It omits prerequisites (Flow tab/session, auth) and what happens on timeout, which matters for a browser-driven mutation.

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 sentences, front-loaded with the action, followed by the return value and the two notable side effects. No filler; only the opening setting list slightly overlaps the later mentions.

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 10-parameter, long-running generation tool with no output schema, the description covers workflow, return value, download side effect, and the credit guard. Gaps are the failure/timeout behavior and the fact that settings persist to the Flow session, but nothing essential to calling it correctly 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 description coverage is 90%, so the schema already explains count, model, aspect_ratio, download_size, max_credits and dry_run. The description repeats the same fields (aspect ratio, model, count, download_size, max_credits) without adding syntax or semantics, and leaves timeout_sec and project entirely to the schema. Baseline 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?

Opens with a specific verb-plus-resource ('Set aspect ratio, model and number of images in Google Flow, submit the prompt, and wait until the images finish') and states the return value ('new media ids'). It is clearly distinct from flow_status and flow_get_options, though it doesn't explain its relationship to flow_download_images despite exposing an inline download option.

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 gives two useful conditional hints: pass download_size to fetch results in the same call, and the tool refuses to run above max_credits. But it never routes the agent to alternatives — e.g. when to prefer dry_run, flow_get_options for previewing settings, or flow_download_images instead of the inline download.

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