search

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

With no annotations provided, the description carries the burden of disclosing behavioral traits. It adds a significant cost warning (100 quota units) that is not in the schema. However, it does not explicitly state that the operation is read-only, nor does it describe pagination, return format, or error scenarios, which are relevant for a search tool without an output schema.

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 two concise sentences: the first states the purpose, the second delivers the cost warning. It is front-loaded with the main action and contains no superfluous words, making it easy to parse quickly.

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?

The tool has no output schema and no annotations, so the description should cover essential context. It provides the purpose and a cost warning, but omits details about return format, pagination, or default sorting behavior. While search is fairly simple, the absence of output information leaves some gaps for an agent deciding whether this tool meets its needs.

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% for all parameters (type, query, maxResults), so the description adds little beyond what the schema already provides. The mention of 'videos, channels, or playlists' maps to the type enum, but this is already captured in the schema. There is no extra semantic detail about query syntax or result interpretation.

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 clearly states the tool searches YouTube for videos, channels, or playlists, which is a specific verb-resource-entity combination. It effectively distinguishes this search tool from sibling tools like list-videos, list-channels, and list-playlists, which are likely for retrieving known resources.

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 includes a cost warning ('Costs 100 quota units per call — use sparingly'), which gives some usage guidance by advising caution. However, it does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusions or alternative tool names, leaving the selection criteria partly implicit.

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