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

Annotations already mark this as read-only, idempotent, non-destructive, and open-worldchers. The description adds value by clarifying the required `engine` and `q` parameters)Skip; wait, that's parameter info. More importantly, it discloses the mapped path and that the upstream canonical path is not mounted, which is a useful behavioral caveat. No contradiction with annotations exists.

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?

The description is four sentences and stays on-topic. It front-loads the main purpose)Skip; then provides required parameters, optional parameters, use cases, and a path note. It is slightly redundant with the schema's required fields and `engine` enum, but overall each sentence earns its place.

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 need not explain return values. It adequately covers input requirements, optional parameters, practical use cases, and the mapped-path caveat. It could additionally mention pagination limits or token freshness, but for a read-only YouTube search tool this is reasonably complete.

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 the baseline is 3. The description mostly paraphrases the schema by restating that `engine` and `q` are required and that `gl`, `hl`, and `sp` are optional. It adds a small amount of extra meaning by giving examples of advanced filters for `sp` (upload date, duration, result type), but not enough to raise the score significantly.

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 first sentence identifies a specific action and resource: 'Search YouTube and get back matching videos, channels, and playlists.' This clearly distinguishes it from sibling tools for Instagram, Reddit, Pinterest, and Twitter search. The tool name and title reinforce the same purpose without ambiguity.

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 explicitly lists three use cases: find video content on a topic, track a channel's recent uploads, and gauge video coverage. It does not name an alternative tool or explicitly say when not to use it, but the given contexts are clear enough for an agent to select it appropriately among sibling search tools.

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