edit_image

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

With no annotations, the description carries the full behavioral burden. It discloses the output format ('Outputs high-res WebP'), the presence of an 'AI quality review' step, and the ability to use multiple reference images. It does not state whether the original images are left untouched or how the output file is returned, but it adds substantial context beyond the schema.

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 well-organized: purpose first, then example operations, then mechanism, then output characteristics. It is a concise four sentences with no major fluff. There is mild redundancy between 'using AI' and 'intelligent editing', which prevents a perfect score.

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?

Given no annotations and no output schema, the description should clarify prerequisites and return mechanics. It specifies the output format (WebP) and aspect ratio support, but does not clarify that reference image(s) are needed despite input_paths not being marked required, nor explain how the resulting WebP is returned (file path, base64, etc.). These gaps make it only adequately 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%, so the baseline is 3. The description repeats that the tool uses reference image(s) + text prompt, but the schema already documents prompt examples and input_paths formats. It adds clarity about combining multiple images, but no new syntax or format details, and leaves ambiguity about whether input_paths is effectively required.

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 opens with a specific verb+resource pair ('Edit images based on text instructions') and lists concrete operations (modify colors, add/remove objects, change backgrounds, combine multiple images). This clearly distinguishes it from siblings like generate_image (creates new images) and crop_image_to_square (mechanical transform). The mention of multiple reference images also sets it apart from single-image edit 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 gives clear context for when to use the tool: whenever existing images need modification based on text instructions, including combining images. However, it does not explicitly name alternatives like generate_image or crop_image_to_square, nor state when not to use this tool, so it misses the explicit routing that would earn a 5.

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