Audio Transcribe

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

Annotations already mark it non-read-only, non-destructive, open-world, and non-idempotent, so the safety bar is partly covered. The description adds real behavioral context beyond that: provenance rules (source cue/word times are assertions, model output is inference), the constraint that local-only forbids cloud, the readback receipt requirement, and the crucial operational fact that no local model is installed.

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?

Purpose is front-loaded and every sentence carries information with no filler. The telegraphic, clause-heavy style ('Supplied cue and word times remain source assertions') is dense and slightly cryptic, which marginally reduces readability.

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 a complex nested request object and an existing output schema, the description covers the key operational facts an agent needs (no local model, backend selection, local-only restriction, receipt-gated readback) and does not need to restate return values. It leaves the request structure itself to the schema, which is acceptable.

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 description coverage is 100%, so the baseline would be 3. The description still adds meaning by tying concepts to fields: caption selection ordering, 'explicit backend' for ASR, local-only forbidding cloud requests, and the receipt-digest/source-identity requirement for readback, which map to backend, local_only, and expected_receipt_sha256.

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+resource: extracting caption intervals or inferring speech from audio via an explicit backend. It is clear what the tool does, but it never names or distinguishes itself from close siblings like media_caption_events, audio_dsp_analyze, or media_perceive, so the agent must infer the boundary.

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 gives ordering/constraint cues ('Caption selection precedes ASR; local-only selection forbids cloud requests; Readback requires the retained receipt digest') which imply when each path applies. However, it never states when to use this tool versus alternative transcription/caption siblings, so guidance remains implied rather than explicit.

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