youtube search

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

Adds real context the annotations cannot carry: 100 quota units per call (1% of the default daily quota), a 25-result ceiling per call, and a hard 20-call limit per server process. The annotations already cover readOnly/openWorld/idempotent, so this extra cost and throttling information is genuine added value. It does not explain pagination behavior despite exposing page_token.

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 what the tool does, then immediately the cost warning, then the constraints. Every sentence carries information; the only minor friction is the quota arithmetic in parentheses, which is worth keeping.

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?

An output schema exists, so return values need not be described, and the quota/call-cap behavior is well covered. However, for a paginated search tool the description says nothing about how page_token relates to the 25-result cap or what order accepts, which an agent needs to page correctly.

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 0%, so the description must compensate and it only partially does: it explains the for_mine/kind='video' coupling and implies max_results is capped at 25. Four parameters — order, page_token, and the accepted values of kind — get no semantics at all, leaving the agent with bare untyped defaults.

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 ("Search YouTube") and names the sort of operation it is not by pointing at the list tools. An agent can distinguish it from youtube_list_my_playlists or youtube_get_videos without inspecting the schema. It falls short of a 5 only because it doesn't spell out what the search covers (videos vs channels vs playlists) beyond the for_mine note.

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?

"Prefer the list tools when possible" is an explicit alternative plus a selection condition, and the quota warning gives an economic reason to follow it. The exclusions are somewhat soft ("when possible" leaves the agent to judge), so it is not a full 5.

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