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

With no annotations provided, the description fully carries the burden of behavioral disclosure. It explains the multi-step payment flow, presigned PUT URL with 1-hour expiry, MPP payment challenge, idempotent retries, auto-refund on failed jobs, and the exact output shapes from get_job_status across different formats. This far exceeds the minimum transparency expected.

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?

The description is long but every sentence earns its place, covering a complex multi-step protocol in a logically ordered flow. It front-loads the core purpose, then systematically walks through the three-call sequence, output formats, pricing, and edge cases without redundancy or fluff.

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?

Given the tool's high complexity (multi-step payment, upload, polling, multiple output formats), the description leaves no critical gap. It covers all invocation phases, return types via get_job_status, pricing, failure handling, and even points to authoritative schemas. No output schema exists, but the description fully explains expected results.

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?

Although the input schema already provides descriptions for all three parameters, the description adds substantial meaning beyond the schema. It explains the call sequence (filename first, then job_id + payment_credential), the purpose of each parameter in context, and additional details like the full Authorization header format and supported filename extensions. This significantly aids correct invocation.

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 'Transcribe audio or video to text, including per-word timestamps for precise editing,' which is a specific verb+resource statement that clearly conveys the tool's core function. It distinguishes itself from sibling tools like summarize or find_clips by focusing on transcription with word timestamps and downstream editing use cases.

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?

The description provides an explicit three-call workflow with numbered steps, specifying exactly when to use each parameter and how to complete the process. It also names concrete use cases (podcasts, interviews, meetings, lectures, clip creation) and notes idempotent retry behavior, giving clear guidance on how to invoke the tool correctly.

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