Edit an image with OpenAI

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

The description adds substantial context beyond the annotations (readOnlyHint=false, openWorldHint=true): files are read only from OPENAI_MCP_ALLOWED_DIRS, results are written back to disk, and an Error Handling section tells agents how to interpret 'File not found' versus permission failures. These details are actionable and not derivable from the annotations alone. No contradiction exists — the described file writes align with readOnlyHint=false.

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 lengthy but well-organized with clear section headers (Args, Returns, Examples, Error Handling) and a front-loaded purpose sentence. The Args and Returns blocks partly duplicate the schema and output schema, which is mild redundancy, but the Examples and Error Handling sections earn their space since they encode behavior not present in structured data.

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 an 8-parameter tool with file I/O, the description covers purpose, parameter meanings, filesystem constraints, failure modes, and usage examples thoroughly. The remaining gap is minor: it never states what happens when output_dir is omitted (the default output location), and the 'Don't use when' guidance covers only one sibling despite several related ones.

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 Arg list in the description largely restates what the schema already documents (ranges, defaults, enum values) rather than adding new semantic depth; a few phrases like 'absolute paths to source images' reinforce but do not extend the schema text.

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 opening sentence states a specific verb phrase ('Edit or extend existing images according to a text instruction, optionally restricted to a masked region') that clearly identifies the resource (existing images) and the operation. It differentiates from the sibling openai_generate_image by explicitly calling out that creating from scratch is a different tool.

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 provides concrete 'Use when' scenarios with realistic examples ('Replace the sky in photo.png with a sunset', 'combining several product shots into one scene') and an explicit 'Don't use when' with the named alternative (openai_generate_image). This is exactly the when/when-not/alternatives guidance the dimension asks for.

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