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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile needs no restating. The description adds genuinely useful behavior not in annotations: the blocking wait window, the retry-until-terminal loop, and a 30-day URL retention warning that affects the user's ability to keep results. However, it does not cover error/failure semantics beyond listing 'failed' as a status, so with annotations carrying the safety load this lands at a solid 3 rather than higher.

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 core read operation, then practical guidance, with no filler sentences. The restatement of wait_seconds' default and max slightly duplicates the schema, but every other clause (Gems charged, 30-day URL, list_history fallback) earns its place.

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?

No output schema exists, so the description correctly carries the return-value burden: status values, result contents, charged Gems, and URL lifetime. Combined with the polling loop and the list-based alternative, an agent has everything needed to call and interpret this correctly.

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 100% and already documents request_id provenance, wait_seconds range, default 45, and the 0-means-immediate case. The description restates the default and cap ("default 45, at most 120"), which is redundant, though it does add the polling semantic of what to do with the returned status. Baseline 3 is the right level when the schema does the parameter work.

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?

Specific verb + resource ("Read a request started with generate") plus the exact payload it returns: status enum, result, and Gems charged. It also draws the key boundary against siblings by noting that Mage-app generations are not requests and appear in list_history instead.

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 polling instruction ("call it again while the status is queued or in_progress"), plus explicit routing to list_history with concrete status values when following many requests. It also states an exclusion (Mage-app generations), which is exactly the when-not guidance most tools omit.

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