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

Goes well beyond the annotations: it discloses pre-flight validation with no charge on refusal, the per-token billing model with usage.cost_rub as the cost field, and concrete latency expectations (an hour of video takes several minutes in exact mode). This matters because readOnlyHint=false alone tells the agent a mutation happens but not that money is spent or how long the call blocks.

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?

Well front-loaded: the one-line purpose and the free-validation guarantee come first, then cost, then mode tradeoffs. Dense but each sentence carries weight; the only slightly expendable line is the raw API-path equivalence.

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 no output schema, the description still characterizes the return shape (timecoded lines, speaker labels, usage.cost_rub) and covers rejection, billing, latency, and mode semantics, which is enough for correct invocation. A fuller return-structure sketch would be the only gap.

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 100%, so 3 is the baseline, but the description adds real meaning: it explains the tradeoff between exact (word-for-word, timecodes, optional speaker labels) and fast (key points, rough timecodes, several times faster and cheaper), which is decision-relevant context the enum alone does not convey.

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 — transcript or summary of a YouTube video by link — and the API equivalence (POST /v1/video/transcriptions) removes ambiguity about what backs it. It does not explicitly differentiate from siblings like transcription_create or video_get, so an agent must infer the YouTube-specific scope from the name.

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?

Gives clear mode-selection guidance (exact vs fast, prefer fast on long videos because exact may exceed the client tool timeout) and lists rejection conditions up front (deleted/private/link-only, live streams, over four hours) so the agent knows when a call will be refused. It never routes the agent to a sibling tool as an alternative, which keeps it short of a 5.

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