generate_image

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

Annotations already include idempotentHint=true, so replay behavior is partly structured, but the description adds valuable detail: the operation_id must be fresh and retained, replaying identical arguments returns the same artifact without another submission, and the tool performs no retries, resizing, or prompt rewrites. The billing note is also an important side effect that annotations 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?

Two sentences deliver a high density of useful information with no filler. The core outcome is front-loaded, and each clause adds a distinct constraint or behavioral detail. Nothing in the description is redundant with the structured fields.

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 no output schema, the description covers the essential operational facts: output type, dimensions, quality, billing, idempotency, and explicit non-behaviors. It does not describe the exact response envelope or authentication requirements, but it supplies enough for an agent to invoke the tool and understand the artifact contract.

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 compensate for the bare schema. It explicitly covers operation_id semantics (fresh UUID, replay behavior), names the exact accepted size and quality ('native 1536x864/high'), and implies the prompt is used verbatim via 'no prompt rewrites'. This meaningfully supplements the schema, even though prompt constraints like maxLength are not restated.

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 states a specific verb and resource: 'Generate one billable Azure PNG'. It also fixes the native size and quality, making the tool's purpose unambiguous. The action clearly contrasts with sibling tools like edit_image and get_operation, so an agent can identify this as the creation 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 verb 'Generate' and the sizing/quality constraints imply the tool is for creating new images, but the description never explicitly says when to prefer it over siblings or what conditions would call for edit_image or get_operation. It provides clear operational context, such as the need for a UUID, but no direct when-to-use versus when-not-to-use guidance.

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