YouTube analytics broken down by dimension

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

Annotations already provide readOnlyHint=true, destructiveHint=false, openWorldHint=true. The description goes beyond annotations by explaining that demographics returns only viewerPercentage and nothing else, warning against converting to absolute viewers. It also clarifies that capped reports are top N, and that zero rows means missing data, not zero views. No contradictions with annotations; the description adds substantial behavioral context beyond the annotations.

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 dense but well-structured: it starts with the core purpose, then lists reports with parenthetical explanations, and ends with critical caveats. Every sentence carries information that aids correct usage. It is long but appropriately so given the complexity of 17 different reports. Front-loaded with the key differentiator and the most useful report. No fluff.

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?

Given the complexity (17 reports, 6 parameters, no output schema), the description is remarkably complete. It covers report selection, parameter interactions (parent, videoIds), behavior on unknown reports, and important data interpretation caveats. The absence of an output schema is compensated by telling the agent what to expect in terms of data shape (e.g., demographics returns viewerPercentage only) and limits. An agent can call this tool correctly without needing further clarification.

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%, so baseline is 3. However, the description adds extensive meaning beyond the schema: it explains the practical purpose of the report enum (e.g., trafficSourceDetail requires parent), defines 'parent' as required by *Detail reports with examples, clarifies that audienceRetention requires exactly ONE video, and notes the caps per report. The description enriches the parameters with context that the schema alone does not provide.

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 identifies what the tool does: it provides YouTube analytics broken down by dimension, explicitly contrasting it with youtube_channel (totals) and youtube_video_insights (one video, flat). It lists all reports and their meanings. This is a specific verb+resource with full clarity.

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 explicitly states when to use this tool versus alternatives: 'the questions youtube_channel (totals) and youtube_video_insights (one video, flat) cannot answer.' It also gives practical guidance on choosing reports (e.g., trafficSource is the most useful for judging thumbnail/title), how to scope with videoIds, and warns about unknown report names being refused with a list. It provides clarity on when to omit videoIds (whole channel) and the requirement for audienceRetention to use exactly one video.

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