edit_image

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

No annotations are provided, so the description carries the full burden. It mentions returning a task id, status, and output URLs, which implies an asynchronous task model, but it doesn't disclose that the tool can poll (via 'wait') or other behavioral aspects like error handling or side effects. This is only slightly more informative than typical bare descriptions.

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 appropriately concise and front-loaded: the first sentence identifies the core action and the second mentions return values. It avoids unnecessary words, though its brevity sacrifices detail that might be valuable.

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?

The tool has 14 parameters, no output schema, and no annotations, making it a complex tool. The description only covers the basic purpose and return values, leaving out critical information about parameter usage, defaults, polling behavior, and how to interpret the response. It is far from complete for an AI agent to invoke correctly.

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 only 14% across 14 parameters, and the description provides zero information about any parameters. With such low coverage, the description must compensate by explaining parameter roles or relationships, but it does nothing, leaving the agent to infer everything from parameter names and types.

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 clearly states it creates an Ideogram V3 task for editing an image, providing a specific verb and resource. It mentions 'edit image' which distinguishes it somewhat from siblings like text_to_image, but it doesn't explicitly compare to reframe_image or remix_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?

There is no guidance on when to use this tool versus alternatives. Sibling tools include reframe_image and remix_image, but the description offers no context for choosing one over the other, nor does it mention prerequisites or typical use cases.

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