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

Annotations already declare write/idempotent/non-destructive, so the bar is lower, and the description adds genuinely new behavior: a 50-credit cost charged on success and the approval gating. It omits what happens on failure (whether credits are consumed), whether the call is async, and how results are retrieved.

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?

Three short sentences, zero filler, with the gating condition and cost front-loaded before the retry rule. Every sentence carries a distinct piece of information.

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 credit-spending mutation with no output schema, the description covers the cost and approval gate but leaves key operational facts unstated: how to observe the result, whether parent_image_id implies an edit rather than a fresh generation, and what failure does to credits.

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 only 20% (idempotency_key alone is documented), so the description must compensate for four other parameters. It gestures at prompt and ratio as approved artifacts and reinforces key reuse, but parent_image_id and proposal_message_id receive no explanation in either schema or description.

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?

States a specific verb+resource ("Generate an image") plus a meaningful precondition (customer has approved prompt and ratio). It does not distinguish itself from plausible siblings such as render or create_image_pack, so an agent cannot route between them from this text alone.

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 a real precondition ("after the customer approves the prompt and ratio") and idempotency guidance ("Reuse a key only for the same request"), which implies when it should be invoked. However, it never names alternatives (render, create_image_pack, create_carousel) or states when this tool is the wrong choice.

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