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

Annotations declare readOnlyHint=false, and the description explains why: transcription output is persisted with the project for later calls, with `force` overriding the cache. That is genuine behavioral context an agent could not read off the annotations. It omits latency/job behavior (siblings job_status and cancel_job exist) and failure modes, keeping it below a 5.

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?

Three sentences, no filler, with the core output shape stated first and the conditional `timeline` behavior last. The opening phrase 'The transcript of a media file's audio' is noun-phrase framing rather than an action statement, a minor structural weakness.

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 an 8-parameter tool with no output schema, the description covers what is returned (word-level timings, seconds), persistence semantics, and the timeline-mapping option, while the schema handles format/language/range details. It leaves open whether the call is synchronous and how long transcription takes, which matters given the surrounding job_status/cancel_job tools.

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 88%, so the schema already documents from/to/force/media/format/language and the baseline 3 applies. The description contributes meaning only for the undocumented `timeline` flag (times mapped through clips rather than source seconds), which is valuable but narrow.

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?

The description names the concrete resource and result: the transcript of a media file's audio, with per-word timings in seconds, plus the engine used. It implies the transcribe action rather than stating a verb outright, and it never names the siblings it is distinct from (search_transcript, caption_from_transcript), so an 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?

It gives an implicit usage signal by explaining caching ('the result is kept with the project for every later call') and the `timeline: true` variant, which tells the agent when the mapped-time mode applies. It never says when to prefer this over search_transcript or caption_from_transcript, nor what a first call costs, so usage is only implied.

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