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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true), the description discloses the economically critical behaviors: coins are spent, a changed price results in no charge and a new quote, failed/canceled upscales are refunded in full, and retries are deduplicated via idempotency_key. This is exactly the kind of context 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?

Four tight sentences, each carrying distinct operational information (what it does, cost contract, refund policy, result polling, retry safety), with the cost warning front-loaded immediately after the purpose. No filler.

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 paid, asynchronous, idempotent mutation tool, the description covers cost preconditions, failure refunds, result retrieval, and retry behavior, and an output schema exists so return formatting need not be explained. Nothing an agent needs to call this correctly is missing.

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 baseline would be 3, but the description adds real meaning: expected_cost must be the exact value estimate_upscale returned and is rejected if stale, and idempotency_key causes a retry to answer the first upscale rather than re-charge. These semantics go beyond the terse schema hints.

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 opens with a specific verb+resource ("Upscale an image or a video") that matches the title and states the operation unambiguously. However, it never distinguishes itself from near-identical siblings such as app_upscale or app_upscale_quote, so an agent cannot tell from the text alone which upscale entry point applies.

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?

It gives clear workflow context: obtain expected_cost from estimate_upscale for these very arguments, poll get_generation for the result, and repeat idempotency_key on a retry. That covers the main sequencing decisions, but it offers no exclusion guidance about when to prefer app_upscale or the quote tool instead.

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