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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description adds substantially beyond that: charging is capped by confirm_cents, a price change refuses and charges nothing, idempotency is keyed on (token, tool, idempotency_key) rather than arguments, cancellation refunds, and outcome_unknown requires checking studio_get_project before retrying. These are exactly the money-safety and retry semantics an agent needs and cannot get from structured fields.

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 cost/action statement, then compact Args and Returns blocks with no filler sentences. Dense jargon (price_changed, outcome_unknown, r_ polling suffix) is packed tightly, but every sentence carries operational information.

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?

With no output schema, the description documents the success return shape (ok, job_id, kind, poll_after_s, cents) and the full error surface (price_changed, blocked, already_rendering, outcome_unknown) plus next-step tools. For a paid, side-effecting three-parameter tool this is complete enough to call and recover from failures.

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 is 3; the description goes somewhat further by elaborating the ceiling semantics of confirm_cents and, importantly, explaining that idempotency is keyed on the token/tool/key triple rather than the argument values, which the schema does not say. It repeats the schema's own note that 0 learns the price, so it is value-adding rather than transformative.

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 ('renders the saved project exactly as it is') and immediately ties it to the cost source (quote.render_cents from studio_estimate_project), which cleanly separates it from the estimate sibling. An agent can tell what this does and what it does not do (it does not modify the project) without opening the schema.

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 guidance on when and how to call: use confirm_cents as a price ceiling, call with confirm_cents: 0 to learn the price of a paid step, free steps just run. It also routes post-call behavior to wait_for_job and cancel_job (refunds) and names studio_estimate_project as the price source, leaving little to inference.

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