Quote an image

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

Annotations already declare readOnlyHint=true, and the description reinforces this with "WITHOUT spending credits" plus non-obvious behavior: failed generations are charged nothing, and closed generations answer generations_disabled/generations_marking_pending at no charge. The idempotency discussion (identical request returns the prior run, pass attempt 2) is useful but blurs into generate_image's behavior and references an `attempt` parameter this schema does not accept.

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 core value proposition and the "call this first" rule are front-loaded, and most sentences carry real information. It is a single dense paragraph with a digression into idempotency/attempt semantics that belongs more to generate_image than to a pricing call.

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?

With no output schema, the description correctly compensates by describing the return payload (credits, width, height, warnings) and the error responses. The only gap is the unexplained model/aspect_ratio semantics and the phantom `attempt` parameter, which could cause a rejected call.

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. It does a good job on `references`, spelling out all three shapes and the meaning of rights_confirmed, but says nothing about `model` (only that its unit_credits drive the price), `aspect_ratio`, or `prompt` constraints, and mentions an `attempt` field that additionalProperties:false would reject.

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?

Opens with a specific verb+resource+scope: "Price one generate_image call WITHOUT spending credits", and immediately enumerates what is returned (credits, width/height, warnings). It is unambiguously distinguishable from the sibling generate_image, which it names directly.

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?

"Always call this first and show the user the price before generate_image" states the exact sequencing rule and the user-facing obligation. It also routes the agent to the correct prerequisite tools for each reference form (upload_image, create_upload, create_asset, or a succeeded generate_image run_id).

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