Search

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

Annotations alone leave the agent puzzling over readOnlyHint=false for a search, but the description resolves this by stating it consumes paid API credits, requires confirm=true, and that 'Read-like POST requests do not publish to social platforms.' It also flags that includeExtras slows the response. This adds real behavioral context beyond the annotations, though it omits rate-limit or failure behavior.

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?

It is front-loaded with the core purpose and return shape, then layers filters and the credit/confirm caveat. Most sentences earn their place, though the dangling is_paid_promotions clause adds noise without a corresponding schema field.

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 10-parameter, no-output-schema search tool, the description compensates well by enumerating returned fields (title, URL, view count, duration, channel, badges) and covering the paid-credit/confirm mechanic. The only gap is the stray parameter reference and no explicit guidance on the sibling tools.

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 the baseline is 3. The description reiterates filtering/sorting/pagination semantics but adds little beyond the schema fields, and it references an is_paid_promotions parameter that does not appear in the schema (which sets additionalProperties:false), which is a mild inconsistency rather than added clarity.

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 description states a specific verb (searches) and resource (YouTube by keyword) and enumerates the returned result types (videos, channels, playlists, shorts, shelves, live streams). Combined with the sibling list (youtube_search_by_hashtag, youtube_search_typeahead, youtube_channel_videos), an agent can tell this is the general keyword search apart from specialized siblings.

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?

It describes capabilities (filter by upload date, sort by relevance/popular, paginate) but never states when to prefer this over youtube_search_by_hashtag, youtube_search_typeahead, or youtube_channel_videos. Usage is implied by the keyword-search framing rather than explicitly guided, so it stays at the minimum-viable level.

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