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

Annotations already declare readOnly=false, openWorld=true, idempotent=false and destructive=false, and the description adds real context: results are written to local files, previews are downscaled while originals keep full paths, and the call can return an asynchronous "running" status. It omits cost/latency implications, moderation behavior, and what overwriting an existing output path does.

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 core capability, then the image-ordering rule, then the async follow-up. Nothing is repeated from the title and no sentence is filler.

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?

An output schema exists, so return values need limited explanation, and the description still covers the async continuation path and file outputs. With 14 parameters, the description reasonably leans on the 93%-covered schema, though it could say more about how mask/markup and n interact with the edit target.

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 already 93%, so the schema carries most parameter meaning. The description still adds a non-obvious semantic rule for the `images` array ordering (first = target, rest = references) plus the file-write behavior, which the schema does not convey.

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?

States concrete verbs and resources: edit local images or create a new image from local reference images, then save results to local files. This clearly separates it from a pure text-to-image generator like generate_image because it requires local input images, but it never names that sibling explicitly.

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?

Provides actionable routing: the first image is the one edited, the rest are references, and if the returned status is "running" the agent must call get_image_result with the job_id. It does not state when to prefer generate_image over this tool or when editing is inappropriate.

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

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

Annotations declare a non-read-only, non-idempotent, open-world write, and the description adds real substance beyond them: images are written to local files, previews are downscaled while originals are returned as paths, and the operation may return a job that is still running. It does not disclose cost, rate limits, or where on disk files land, which keeps it off 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 what the tool produces before the async fallback instruction. "Supports raster output and animated GIF" mildly overlaps the output_format enum but still frames the tool's scope early.

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 13-parameter generative tool with an output schema, the description covers the essentials an agent needs: what is produced, where it is saved, what the return contains, and how to handle a still-running job. Nothing required to invoke 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 92%, so the schema already explains prompt, size, model, quality, GIF frame settings, and compression. The description adds no parameter-level meaning of its own, which is the expected baseline when the schema does the work.

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 names a specific verb and resource ("Generate images from a text prompt") plus the side effect ("save them to local files") and output modes (raster, GIF). It does not explicitly distinguish itself from edit_image, though the async handoff to get_image_result gives partial sibling routing.

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?

"If the result has status 'running', call get_image_result with its job_id" is explicit conditional guidance naming the alternative tool and parameter to pass. It lacks any statement about when to call generate_image versus edit_image, which is the remaining ambiguity among siblings.

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

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

Annotations already establish this as a read-only, closed-world operation, and the description adds genuinely new behavioral information: the call blocks for a limited time and is a polling primitive that must be repeated. It does not describe what is returned or how non-running terminal states are surfaced, which is a modest remaining gap.

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?

Two short sentences, front-loaded with the action and followed by the retry rule. There is no boilerplate or redundant restatement of the title.

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?

An output schema exists, so return values need not be explained, and the polling contract is fully conveyed. The only omission is how error or failed-completion states differ from "running", which would help an agent decide whether to retry.

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?

Only one parameter exists and schema coverage is 100%, with the schema already explaining that job_id is the value returned by generate_image or edit_image. The description repeats that provenance without adding format, validation, or lookup semantics, 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?

States a specific verb and resource ("Wait for and return the result of a job") and scopes it to jobs produced by generate_image or edit_image, which cleanly separates it from those two sibling tools. An agent can identify the tool's role without opening the 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?

Gives a clear triggering condition — use it only for jobs the generating tools reported as "running" — and prescribes the follow-up action (call again if still running). It stops short of an explicit exclusion such as behavior for already-completed or failed jobs, so it is strong but not fully exhaustive.

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