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

Beyond the annotations it discloses the behaviors an agent actually needs: the edit produces a new version while the old one is retained (consistent with destructiveHint=false), it costs one image credit per result, and explicit/hateful/misleading instructions are refused at no cost. The cost and moderation-refusal details are not derivable from the annotations or schema and directly affect whether the agent should call it.

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 short sentences with the core action and scope front-loaded, examples immediately after, then cost/retention/refusal facts and the follow-up call. No filler and nothing buried.

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 non-idempotent mutation with no output schema, the description covers cost, retention of the prior version, failure mode, and the follow-up retrieval call, which is nearly everything an agent needs. The only gap is that it doesn't explain how multiple versions come back or how to choose among them, which the agent must infer from the schema and get_image_set.

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%, so instruction and generation_id are already documented, and the description reinforces the instruction's style ("short instruction", one sentence) with examples. The optional versions parameter (1-5 simultaneous variations) is never addressed in the description, and the phrase "the result is a new version" is singular, which slightly under-represents multi-variation use.

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 ("Changes") and resource ("one finished image") and clarifies the change scope with two concrete instruction examples ("warmer light, add a marble counter", "make the headline say Leak-proof"). It also pins down what is preserved ("Keeps the product and everything else the same"), which implicitly separates it from regenerate-style siblings, but it never names the close alternatives such as recolour_image_set or redo_image.

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?

Use context is clear: you need a finished image and a short corrective instruction, and the tool ends with an explicit next step ("Then call get_image_set."). There is no explicit when-not guidance or named alternative for cases where the agent should regenerate or recolour instead, so it stops short of a 5.

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