edit_image

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

No annotations exist, so the description carries the full burden; it does add real value by stating the source image stays intact and the edited result is written as a new resource, which signals non-destructive behavior. However, it is silent on cost implications despite dedicated allow_paid and max_cost_usd parameters, and says nothing about permissions, failure modes, or whether dry_run is honored.

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?

Two short sentences with no filler, and the key constraint (source image preserved, output is a new asset) is front-loaded. The phrase 'input_references do endpoint /images' is slightly jargon-heavy but does not waste space.

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?

An 11-parameter image-editing tool with cost controls, a dry_run flag, output routing, and no annotations or output schema demands far more description than two sentences. The critical cost-safety parameters (allow_paid, max_cost_usd) and the dry_run switch are never mentioned, so an agent could invoke a paid operation unintentionally.

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% across 11 parameters, yet the description only gestures at input_image_path and leaves prompt, model, size, resolution, aspect_ratio, output_dir, filename, dry_run, allow_paid, and max_cost_usd entirely unexplained. An agent cannot tell from the description what units 'size' takes, what 'resolution' means alongside it, or what the paid-operation guardrails do.

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 names a specific verb and resource ('Edita uma imagem local'), and clarifies the mechanism ('usando input_references do endpoint /images'). It does not differentiate itself from close siblings such as generate_variations or animate_image, which also produce derived images, so the agent must infer the boundary.

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 explicit statement of when to use this tool versus generate_image, generate_variations, or animate_image, all of which operate on images. The only implicit signal is 'imagem local', which hints the input must be an existing local file, but no exclusions or prerequisites are given.

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