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

With annotations covering mutation/safety hints, the description adds substantial operational context: asynchronous job semantics, returned { jobId, sessionId, status }, polling vs webhook, 10-40 second typical duration, permission requirement (ai.generate, with role exclusions and 403), credit cost and refund behavior, no-credit failure mode, and explicit advice not to retry. This far exceeds what the annotations disclose.

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 front-loaded with the core action and async behavior, and every sentence carries information useful for correct invocation or integration. It is necessarily long given the async job, credit, permission, webhook, and integration details, though a bulleted structure could improve scanability.

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 complex asynchronous, credit-consuming, permission-gated tool, the description covers all agent-relevant behavior: return shape, polling/webhook options, timing, integration with create_post, permission errors, credit costs, refunds, and no-credit guidance. The presence of an output schema does not leave gaps, and the description is complete for correct use.

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 100%, so the parameter descriptions already document prompt, model, quality, aspectRatio, sessionId, workspaceId, and referenceImages thoroughly. The description adds only marginal parameter meaning, such as reusing sessionId to group related images; baseline 3 is appropriate when the schema does the heavy lifting.

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 and resource ('Start generating an image from a prompt') and immediately distinguishes the tool from siblings by naming get_image_job for polling, create_post for using the result, and upload_media as unnecessary. An agent can identify exactly what this tool does and how it differs from adjacent 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?

Gives explicit post-call workflow (poll get_image_job every few seconds until completed/failed, or wait for image.completed/image.failed webhook) and routes the result into create_post's mediaUrls instead of upload_media. It also states when not to retry automatically after a no-credit failure, covering both how and when to use the tool versus alternatives.

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