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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses important behavior: it costs credits, returns the image inline with id and credits_remaining, and supports references. This adds meaningful context about side effects and performance that annotations alone do not convey.

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 dense but every sentence earns its place, front-loading the core function and cost warning before model guidance. The semicolon-separated model guidance is compact and readable despite covering multiple variants.

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?

Given six parameters, three enums, no output schema, and the readOnly/destructive annotations being neutral, the description covers cost, return format, model choice, reference limits, and resolution constraints. It could additionally clarify default resolution or project_id semantics, but these are either schema-provided or not essential to invocation.

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 coverage is high at 83%, but the description adds value beyond the schema by explaining when to use each model, what the model names mean, the 14-reference limit, and the GPT 2K resolution restriction. This supplements the enum descriptions with practical decision-making context.

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 opens with a specific verb and resource: 'Generates an AI image,' which makes the core function immediately identifiable. It also clarifies scope by listing concrete outputs and referencing siblings like get_pricing, distinguishing this tool from video/sheet generation tools.

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 gives explicit model-selection guidance with conditions for each variant, plus a note to consult get_pricing for credit costs. However, it does not state when to choose generate_image over sibling tools like generate_sheet or generate_video, so the exclusion guidance is incomplete.

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