transcribe_audio

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

No annotations are provided, so the description carries the full transparency burden. It discloses the access restriction (must be inside allowed path), the unavailability of chat uploads, and the recommended behavior on access-denied errors. However, it does not explicitly mention potential side effects like whether persist=True saves to history (covered in schema) or whether the transcription is fully local. It adds substantial context beyond the schema but still has some gaps.

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 structurally efficient: a one-sentence purpose, an IMPORTANT constraint block, and a concise error-handling paragraph. Each sentence adds value with no redundancy, and the critical warnings are front-loaded for quick scanning.

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 complexity (5 parameters, engine alternatives, language defaults) and the presence of an output schema (so return format is documented), the description covers the essential usage context: local file requirement, chat uploads inaccessible, and error handling. It does not explicitly mention when to prefer start_watch for continuous/batch transcription, but the description remains sufficiently complete for an agent to use the tool correctly.

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?

The input schema has 100% parameter coverage with detailed descriptions for all 5 parameters, so the baseline is 3. The description adds important semantics for the path parameter: it must be on the Mac filesystem in the allow-list, and chat uploads are not accessible. This is not fully captured in the schema's path description, making the overall parameter understanding richer.

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 a precise verb and resource: 'Transcribe a local audio file and return the transcript.' This clearly identifies the tool's purpose and distinguishes it from sibling tools such as cancel_transcription, list_models, and start_watch, which are support operations rather than the core transcription action.

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 explicitly states when to use the tool: for local files inside the allow-list, and it excludes chat uploads. It also provides specific error-handling guidance: if access-denied, do not attempt alternatives (downloading models, external APIs, in-process speech recognition); instead ask the user to save the file locally and retry. This is clear when-to-use and when-not-to-use guidance.

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