Audio Clip Export

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

Adds real context beyond the annotations: originals and prior exports remain unchanged, caller-chosen output paths and overwrites are rejected, output is always a new unique 16kHz mono WAV. This coheres with destructiveHint=false and idempotentHint=false and explains why repeated calls are non-idempotent, though it says nothing about failure modes or the 240s/8MiB bounds beyond what the schema already carries.

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?

Four short, front-loaded sentences with no filler; the output artifact and immutability guarantee lead. The final sentence about image_manifest_read is slightly cryptic without more context, keeping it from a 5.

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?

With an output schema present, return values need no explanation, and the annotations plus description together cover safety, idempotency and mutation scope for a single nested request object. Nothing essential to invoking it correctly appears 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 description coverage is 100%, so file_path, expected_source_sha256, start_seconds and end_seconds are already documented, including the omitted-endpoints behavior. The description's phrase 'whole or one-sided' merely restates what the schema says and adds no format or semantics for the SHA-256 requirement.

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 (export) and resource (whole or one-sided audio selection) plus the exact output artifact: a unique private 16kHz mono WAV. An agent can distinguish this from sibling media tools like video_clip_export or audio_transcribe immediately.

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?

It clarifies scope (whole selection when endpoints are omitted, one-sided otherwise) and points to image_manifest_read for a verified restart, which gives some routing value. But it never states when to prefer this over audio_transcribe, media_edit_footage, or video_clip_export, nor any prerequisite like needing a prior manifest/source ingest.

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