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

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered; the description adds the failure-path behavior agents actually need — that a missing transcript is reported explicitly rather than being an error, and that a second call with ai_fallback is the recovery path. Credit costs and async delivery for fallback are disclosed in the parameter description rather than the main text.

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, front-loaded with what it does and which inputs it accepts, followed by the failure/retry guidance. No filler or restatement of the title.

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?

Output schema exists, yet the description still surfaces the two result fields critical to decision-making (captionsUnavailable, available) and the follow-up action. For a read-only, single-required-parameter tool this covers everything an agent needs before and after the call.

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 already 100%, so the baseline is 3; the description goes beyond by explaining the cross-parameter retry flow (ai_fallback only after a prior call reports availability) and by naming the result fields that signal caption unavailability. The per-parameter meaning of chunks/markdown/timestamps is left to the schema, which is appropriate.

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 (fetch the full transcript) and enumerates the exact source types accepted (YouTube ID/URL, TikTok, Instagram, direct media URL). An agent can distinguish this from search_videos or list_channel_videos purely from this sentence.

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 a clear conditional workflow: when no transcript comes back, inspect aiFallback.captionsUnavailable and aiFallback.available, and only then retry with ai_fallback: true. It does not discuss when to prefer this over sibling discovery tools, but for a leaf retrieval tool the key decision path is covered.

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