edit_image

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states that edited images are saved to disk and appended to an HTML gallery, and that it returns absolute paths and the gallery path. This covers side effects and return behavior. It does not mention permissions or whether original files are overwritten, but the mention of 'new images' implies non-destructive behavior. Overall, it provides meaningful behavioral context beyond a bare operation.

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 structured with a clear opening sentence, a behavioral summary, and a parameter list. It is slightly verbose but every sentence adds value. The key behavioral facts are front-loaded, and the parameter details are organized for quick reference. It could be tightened slightly, but it is appropriately sized for a tool with three parameters and side effects.

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 the tool's complexity (3 params, side effects, output schema), the description covers the essential context: it explains input requirements, the editing process, the return values, and the model selection mechanism. It does not explicitly address file overwrite behavior or permission requirements, but it does state that new images are returned, implying safe handling. The description is sufficient for an agent to call the tool correctly without further lookup.

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 0%, so the description must fully compensate. It does so by explaining all three parameters: prompt (instructions), image_paths (existing local files), and model (with defaults and reference to list_models). Each parameter is given a clear semantic meaning that goes well beyond the schema's type-only definitions. This is exemplary parameter documentation.

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 ('edit'), a clear resource ('existing local image files'), and the method ('using a text instruction'). It distinguishes from siblings by explicitly requiring existing files, which sets it apart from generate_image and list_models. The purpose is unambiguous.

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 implies usage by requiring 'paths to existing image files' and noting the edited images are saved, but it does not explicitly name alternative tools or state when not to use it. The reference to list_models for the model parameter gives some guidance, but no direct comparison to generate_image is provided. The 'must be paths to existing' hints at a prerequisite but leaves the alternative selection to inference.

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