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

Annotations only tell the agent this is a non-read-only, non-destructive, closed-world write; the description adds real behavior on top: the artifact is filed next to the source, the text is also returned inline, and the write scope is required. It also declares cost behavior ("Free: nothing is charged"), but that sits awkwardly against the budgetUsd parameter with a default of 2 and max of 10, leaving the actual billing semantics ambiguous.

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 sentences with the core action front-loaded, then side effects, then cost, then auth. Every clause carries information an agent would otherwise have to guess at, and nothing is repeated.

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, the description does not need to enumerate return fields, and it still usefully notes that the transcript comes back inline alongside the file. Coverage of scope, duration limit, side effect, and auth makes it complete for a four-parameter tool; only the unresolved free-versus-budget conflict keeps it from a 5.

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 media_key, names, format, and budgetUsd are already documented in structured data, which sets the baseline at 3. The description's only parameter-adjacent contribution is restating the srt/vtt options, and it never reconciles the "free" claim with the budget parameter, so it adds no new meaning 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?

"Transcribe a video or audio file in the media library ... into a word-timed .srt or .vtt" gives a specific verb, a specific input source, and concrete output artifacts. The 20-minute ceiling and the word-timing detail further pin down what this produces, so an agent can distinguish it from siblings like probe_media or edit_footage without opening the schema.

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 establishes the context of use (an existing item in the media library, capped at 20 minutes) and states the prerequisite "Needs the write scope," which is actionable pre-call guidance. It stops short of naming when-not-to-use or an alternative sibling for longer files, so it is clear but not fully routing.

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