transcribe_audio

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

No annotations provided, so description carries full burden. Discloses experimental status, local/offline execution, background async behavior (returns job_id), automatic model loading, and post-completion file saving. Minor gap: does not explicitly state whether tool modifies the project audio or is read-only relative to the project state.

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?

Lengthy but every sentence provides actionable guidance (setup requirements, polling intervals, post-completion user notification). Logical flow from identification → prerequisites → execution model → monitoring → parameters. Minor verbosity in post-completion instructions ('TELL the user... Always tell the user...').

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?

Comprehensive for a 3-parameter async tool with no output schema. Covers experimental caveats, monitoring workflow, sibling tool relationships, and parameter semantics. Minor gap: does not specify output file format (SRT, TXT, JSON, etc.) despite mentioning file location notification.

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 0% but description fully compensates via Args block: enumerates valid values for model_size ('tiny', 'base', 'small', 'medium', 'large-v3'), explains language format ('ISO language code') and None behavior ('auto-detect'), and clarifies task options ('transcribe' vs 'translate' to English). All defaults documented.

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?

Clear specific verb ('Transcribe') + resource ('entire project audio') + implementation detail ('faster-whisper'). Explicitly distinguishes from sibling 'transcribe_selection' by scope ('entire project' vs implied selection-based), and from 'transcription_set_model' via explicit prohibition.

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-not ('Do NOT call transcription_set_model first'), explicit alternative tool named ('Use check_transcription_status'), specific polling frequency ('10-15 seconds'), prerequisites ('Requires separate setup'), and failure handling protocol ('point them to Transcription Setup docs').

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