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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true, not idempotent). The description adds crucial context beyond that: the free-plan quota (3 exports/month vs unlimited in-editor), the plan gating on WAV and stems, and the wait-then-poll behavior. It does not describe failure modes or exactly what happens to an in-flight export if the wait expires, but on a non-destructive operation the gaps are minor.

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?

Two sentences, front-loaded with what is actually rendered and returned, second sentence covering fallback and quota. No filler; every clause earns its place and the most decision-relevant fact (the free-plan wall) is highlighted.

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 6-parameter write-ish operation with no output schema, the description covers return value (download URL, license PDFs), plan gating, quota, wait behavior, and fallback routing. There is nothing an agent needs in order to call it correctly that 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 33%, so the description must carry weight; it names the parameters that matter (wait_seconds, stems, format, licenses, loudness) and ties each to a behavioral consequence (plan gating, license PDFs, wait-then-poll). It adds meaning beyond the schema in the right way — mapping parameters to outcomes rather than restating them.

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 — render and download the episode — and enumerates the processing pipeline (cuts, ducked music, loudness normalisation, ID3 chapters) plus the return value (download URL, license PDFs). Clearly distinguishable from siblings like cast_get_task, which it explicitly names as the polling alternative.

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 when-to-use routing is given: it names cast_get_task {kind:"export"} as the fallback when the synchronous wait expires, and it names an in-editor alternative for the free-plan wall case with a concrete action (send the user to the project link). This is stronger than the usual when-to-use guidance.

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