Edit Image

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

Annotations already flag this as destructive, open-world and non-idempotent; the description adds genuine context beyond them by disclosing the refine-then-confirm flow, that out-of-scope edits are declined with a link to the editor, and that the artifact is persisted to the user's workspace and returned as a URL. It stops short of mentioning credit consumption or that a sibling (revert_edit) exists to undo a destructive edit, which would have completed the risk picture.

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?

Front-loaded with the core action, then cleanly organized into an operation bullet list, an exclusion note, the two-step flow, and an output note — each block earns its place. Slightly verbose in the closing sentence about accounts and brand kits, but no sentence is wasted.

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 nine-parameter destructive mutation with no output schema, the description covers the workflow, the safety gate, the scope limits and the return destination well. The one material hole is how to point the tool at an existing visual (source_image_url vs generation_id vs output_id), which no structured field explains and the description never addresses.

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 carry the load, and it does well for the two required parameters — operation's four enum values are each defined with examples, and instruction is explained by analogy. But six of nine parameters (source_image_url, generation_id, output_id, output_index, format, and the instruction/confirmed_instruction relationship) are never explained, including the critical question of how the agent identifies which visual to edit.

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 ('Edit') and resource ('a visual in the user's Canvora workspace') and then enumerates the exact operation categories with examples, so an agent can tell this apart from convert_image, create_variation or localize_generation. It also explicitly bounds scope by naming what the tool will NOT do (subject/scene changes are declined), which is rare and useful.

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 per-operation selection guidance with concrete example instructions for each of the four enum values, states the mandatory two-step call sequence, and adds a hard procedural rule ('Always show the user the edit plan before confirming'). An agent has essentially no inference left to do about when and how to call it.

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