addAudio

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

Annotations declare readOnlyHint=false, destructiveHint=false, openWorldHint=false, so the safety profile is already known; the description adds that placing on the voiceover lane drives transcription ('the lane is not only cosmetic') and the fade-sharing rule for short tracks. It doesn't discuss permissions or whether the operation is reversible/undoable, but goes well beyond the annotations.

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?

Front-loads the core action ('Lay an ALREADY-IMPORTED audio file...'), then sequences prerequisites, then parameter semantics. Dense but nearly every sentence earns its place; the all-caps and em-dash style is a bit informal but readable.

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?

A 9-param mutation tool with almost no schema descriptions and no output schema; the description compensates with prerequisite routing and per-parameter meaning. It leaves projectId semantics to the schema (which documents it) and doesn't state the return, but that is minor for this operation.

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 only 11%, so the description must carry parameter meaning – and it does: assetId must be an audio-kind asset, endSec omission plays the whole file, offsetSec is the in-file playback start, gainDb 0/negative meaning, kind picks the lane, fadeInMs/fadeOutMs ranges and default and the short-track sharing behavior. Six of nine parameters get explicit semantics beyond 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?

States a specific verb and resource ('Lay an ALREADY-IMPORTED audio file over the recording across a span of the edited timeline'), with the use cases (voiceover, music bed) named. Distinguishes itself from sibling setAudio by requiring an already-imported asset and placing it on a span of the timeline.

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?

Explicitly says to use getCurrentDocument to find audio assets, to use importMedia first if none exists, and 'never guess an id'. These are concrete when-to-use and prerequisite instructions that route the agent to the right siblings.

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