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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered; the description adds genuinely useful context beyond that: cost of at least 10 credits, that repeated requests may repurchase data, and that includeExtras slows the response. However, the pasted pricing/marketing boilerplate ("Search API View Pricing... Response format video. 1 credit per request") is ambiguous against the stated 10-credit minimum, leaving the true cost model unclear.

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 same four-sentence block appears twice verbatim, and a raw pricing blurb is pasted in the middle of it, so the reader must reconcile duplicated and partially conflicting statements. The front-loaded first sentence is good, but the repetition and boilerplate waste a large fraction of the text.

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 a read-only search with no output schema, the description does cover return fields, filtering, sorting, and cost, which is most of what an agent needs. The mismatched parameter names and the duplicated, price-contradictory block mean an agent could still call it incorrectly or misjudge spend.

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?

With schema coverage at 50% and 8 parameters, the description does add meaning for uploadDate filtering, relevance vs popularity sorting, and what includeExtras yields. But it references two parameters that are not in the schema (is_paid_promotions, continuationToken instead of cursor) and never explains type, region, or the shorts-vs-videos distinction that the enum implies.

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?

Opens with a specific verb+resource ("Searches YouTube by keyword query") and enumerates the result types returned (videos, channels, playlists, shorts, shelves, live streams), which lets an agent distinguish it from social_youtube_video_detail or social_youtube_channel_videos. It stops short of naming the closest siblings such as social_youtube_search_hashtag or social_youtube_search_typeahead, so the boundary is inferable rather than stated.

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 implies usage (keyword search with optional upload-date filtering, sorting, and pagination) but never states when to choose this over sibling search tools. It also tells the agent to "set is_paid_promotions=true" and to paginate with "continuationToken", neither of which exists in the schema (the actual parameter is cursor), which is actively misleading guidance for invocation.

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