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

Goes well beyond the annotations: discloses cost (Gems), concurrency limits shared with the Mage app with the specific error token `too_many_requests`, batch-in-waves advice, and the fact that an idempotent retry returns the original request without charging again. This is exactly the mutation cost/idempotency context an agent needs and that annotations cannot express.

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?

Front-loaded with the action and payment model, and nearly every clause carries real information. The middle section is a long semicolon-chained block that could be broken into ordered steps for faster scanning, which is the only deduction.

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?

Covers the full call lifecycle for a complex, paid, stateful operation: pricing pre-check, model selection, media input handling, rate-limit behavior, idempotency, and the returned request_id plus the follow-up tool. With no output schema, it still tells the agent what comes back.

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 baseline is 3, but the description adds the config layering model onto model defaults, the @handle convention, and https/data URL handling. The idempotency guidance adds one genuinely new consequence (no double charge on retry), though much of the rest restates the schema's own parameter descriptions.

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 family ('Start an image, video, or audio generation') plus the payment model ('paid in Gems from the account'). It is immediately distinguishable from siblings like estimate_cost, list_models, and get_request, all of which it names.

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?

Explicit ordering guidance: check price with estimate_cost first, pick model_id from list_models, upload large local files with create_upload first, and poll with get_request. It also states an exclusion-style rule for idempotency_key reuse (only on retry of a lost response).

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