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

Far beyond the annotations: discloses the 2-cent price, that the charge never exceeds confirm_cents, the price_changed refusal path with nothing charged, and that idempotency is keyed on (token, tool, idempotency_key) rather than on arguments — a non-obvious trait an agent would otherwise get wrong. It also sketches the post-call workflow (poll_after_s, wait_for_job, studio_get_project, studio_render, cancel_job).

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 cost and definition, then Args/Returns in a compact labeled layout. Slight redundancy — 'Costs 2 cents' is repeated by the confirm_cents ceiling explanation, and the schema already words confirm_cents similarly — but overall the density mostly 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?

With no output schema, the description is required to explain the return shape, and it does ({ok, project_id, job_id, kind:'render', poll_after_s, cents}), plus the job id prefix and the follow-up/poll/cancel steps. For a paid, non-idempotent-by-argument mutation this is complete enough to call correctly on the first try.

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?

Adds meaning the 67%-covered schema cannot: library_id is sourced from library_list, confirm_cents is a ceiling with the special 0-to-inspect behavior, and idempotency_key is tied to the purchase-retry semantics. These are usage-critical semantics rather than restatements of the type definitions.

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 concrete verb+resource ('listens to a voice recording from your Library and makes a Studio project from it') and pins the scope with 'from your own audio' plus 'scenes timed to your voice', which cleanly separates it from generic project-creation siblings like studio_create_project.

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 strong operational guidance: call with confirm_cents: 0 to learn the price, free steps just run, and refusals return price_changed charging nothing. It does not explicitly name a competing tool (e.g. studio_create_project) as an alternative, so it stops short of full when-not routing.

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