Generate image (GPT-image)

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

With no annotations, the description discloses return values (image URL, local path) and configuration behavior (per-call overrides). It does not address potential API failures, rate limits, or side effects of saving files, but it does provide useful context about how the tool operates.

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 sentences that front-load the primary action and then add configuration and return details without redundancy.

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 tool with 6 parameters, no annotations, and an output schema, the description covers purpose, configuration, and key outputs. It omits details on count, size, and quality, but these are accessible in the schema and the description otherwise gives a solid overview.

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?

The description explains the prompt (text prompt), model (config default with overrides), and save (save_dir/save flag), but does not clarify n, size, or quality despite the schema having 0% coverage. It adds some meaning but leaves several parameters under-specified.

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?

Description states 'Generate one or more images from a text prompt via the configured OpenAI-compatible image API.' This clearly identifies the action (generate), resource (images), and method (API), and is distinct from sibling tools like get_config and list_image_models.

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?

Mentions that endpoint/key/model come from config and that per-call args override them, directing users to get_config/set_config for configuration concerns. However, it does not explicitly state when not to use this tool vs. list_image_models or set_moderation, so it lacks explicit exclusions.

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