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

Annotations already indicate read-only, open-world, non-destructive behavior. The description adds valuable context by calling it a 'metered live-data request' and noting 'exact publication data when available,' which signals potential variability or cost. This goes beyond the annotations without contradicting them.

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 remarkably concise, using two short sentences to state the purpose, list return data, and mention metering. It front-loads the main verb and resource, and every sentence adds new information without redundancy. This is appropriately sized for a tool with a single parameter.

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 return types are already covered. The description covers the core behavior, data fields, and metering, which is sufficient for a simple read-only call. It does not mention error handling or rate limits, but these are less critical given the annotations and output schema. Overall, it is quite complete for its complexity.

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?

The schema provides only the pattern for video_id with no description (0% coverage). The description clarifies that video_id is a YouTube video ID, but it does not explain the encoding, validation, or any nuances beyond the pattern. It meets the minimum requirement but does not fully compensate for the schema's lack of detail, though the parameter is straightforward.

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 fetches fresh metadata and engagement for a YouTube video ID, specifying a concrete verb (fetch) and resource (video ID). It also lists the exact data fields returned (views, likes, comments, duration, tags, categories, channel identity), which distinguishes it from sibling tools like get_youtube_channel or get_youtube_video_transcript, even if not explicitly named.

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 for retrieving current video data but does not explicitly state when to choose this tool over alternatives. There is no mention of exclusions or criteria like 'use this for metadata, use transcript for text.' The metered/live-data note hints at cost implications but no direct guidance against using other tools.

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