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

Annotations only cover the safety profile (readOnlyHint false, destructiveHint false, idempotentHint false); the description adds substantial context beyond them: uploading consumes normal plan minutes, transcription starts immediately on upload, authorization renews automatically while connected, omitted settings fall back to saved presets or service defaults, and results arrive via the widget with a recording ID to poll on get_transcript.

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 action and the pre-upload review requirement, and most sentences carry distinct information (re-entry, cost, polling, alternatives). It is on the long side at roughly nine sentences, with some UI-widget detail that could be trimmed.

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?

An output schema exists, so return values need no explanation, yet the description still supplies the workflow an agent needs: the widget surfaces settings and recording IDs, then the agent polls get_transcript per recording. Combined with the default-fallback behavior and cost note, nothing critical for correct invocation 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 70%, and the description adds genuinely useful semantics not in the schema — the omitted-parameter fallback rule (saved preset or service defaults) and the pairing of speaker labels with name/count. It does not address customPrompt, importantTerms, translateTo, or note, leaving four parameters to the schema alone.

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 — 'Prepare an uploader with the agreed transcription settings' — plus concrete scope details (up to 20 files, each file gets its own recording ID). It explicitly routes away from two siblings: retranscribe_transcript for later setting changes and transcribe_url for public media URLs.

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 explicit preconditions ('Review language, speaker labels/names/count, style and other preferences with the user first'), describes the re-entry pattern ('Call start_upload again to change settings before uploading'), and names alternatives with the condition selecting them (transcribe_url for public URLs, retranscribe_transcript for post-hoc changes).

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