youtube_analytics_top_videos

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states results are sorted by view count and exclude Shorts, which is useful. However, it doesn't disclose what per-video metrics are returned beyond sorting, whether this requires authentication/premium access, rate limits, or what error behavior looks like. For an analytics tool with zero annotation coverage, this is a moderate gap.

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 compact and well-organized. It leads with a clear summary sentence, then a return-value note, then structured Args with defaults. Every line earns its place with no irrelevant filler or redundancy. At roughly 40 words of useful content, it's appropriately sized for a simple 3-parameter analytics tool.

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 tool with no annotations, no output schema, and 0% schema description coverage, the description provides the essential basics: purpose, return value, and parameter defaults. However, it lacks disclosure of what metrics are included beyond view count, whether this requires channel authentication (given siblings like youtube_auth exist), and does not explain the excluding-Shorts behavior in sufficient detail to help an agent reason about data completeness.

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 input schema (0% description coverage) provides parameter names and defaults but no formatting details. The description adds date format guidance (YYYY-MM-DD), default behaviors for all three parameters, and the max_results cap of 200, which exceeds what the schema documents. However, it doesn't explain the relationship between date range and metric calculations or any constraints on valid date ranges.

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 returns top-performing videos by view count, uses a specific verb (get) with a clear resource (top videos). It distinguishes from siblings like youtube_analytics_top_shorts by explicitly excluding Shorts, and from youtube_analytics_overview by focusing on per-video metrics sorted by view count. However, it doesn't explicitly name sibling alternatives, which would strengthen differentiation.

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 explains the default date ranges (28 days ago to today) and that results are sorted by view count excluding Shorts, providing useful usage context. However, it doesn't explicitly state when to choose this tool over siblings like youtube_analytics_top_shorts or youtube_analytics_video_detail, or mention what the output metrics include. The 'excluding Shorts' is the main differentiator but remains implied rather than explicit guidance.

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