transcribe

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

With no annotations, the description carries the full burden and does so well: it discloses chunking behavior for long files ('cut at a pause and sent one piece at a time'), the 10-second overlap at joins with speaker number reconciliation, the wait_seconds default of 25, and that an unfinished job returns an id. The anti-polling instruction is exactly the kind of behavioral constraint an agent cannot infer elsewhere.

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?

Content is front-loaded and nearly every sentence carries distinct information, but the style definitions are delivered in a dense, telegraphic run of short sentences ('style clean drops fillers...', 'style raw_dictation drops punctuation...') that could be grouped more legibly. Slightly terse phrasing ('Waits wait_seconds (default 25)') costs a bit of parsing effort.

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 tool with no annotations and no output schema, the description covers the async job flow and the transcription-quality knobs thoroughly. It never says what a completed transcript result looks like (text field, timestamps, segments) or which audio formats are accepted, which is the main remaining gap for an agent planning the call.

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% and the schema has no enum for style, yet the description enumerates and explains all four style values (verbatim, clean, technical, raw_dictation) and their output differences. It also constrains speakers to 2-8, forbids it with style technical, and explains wait_seconds semantics, leaving only the trivial path parameter to the schema.

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?

Opens with a specific verb+resource ('Speech to text for one audio file or one YouTube link'), including the key scope limit of one input. It implicitly separates itself from siblings like translate and ask_about_audio, but never names them, so the differentiation is inferential rather than explicit.

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 strong operational guidance: which style to choose, that speakers must not be combined with style technical, that speakers must be 2-8, and explicitly what to do when a job id is returned ('Tell the user, then call get_job_status. Do not poll in a loop'). It does not explicitly say when to prefer translate or ask_about_audio instead, so it stops short of full alternative routing.

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