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 transparency burden. It discloses key behavior: returns per-video metrics, sorted by view count, excludes Shorts, and it also documents default date ranges and the max result cap. It does not mention authentication or rate limits, but for a read-only analytics tool this is reasonably transparent.

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 front-loaded with a one-sentence purpose, then a concise return-behavior line, followed by a compact Args list. Every sentence adds useful information, with no filler or redundancy.

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 tool has three optional parameters and no output schema, the description covers parameters, defaults, sorting behavior, and Shorts exclusion. It falls slightly short of a 5 because it does not enumerate the exact per-video metrics returned or mention authentication prerequisites, but it is largely complete for this purpose.

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 0%, so the description fully compensates. It explains each parameter: start_date with format and default, end_date with default, and max_results with a maximum of 200. This adds meaning well beyond the bare schema types and defaults.

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 opens with 'Get top-performing videos by views,' which is a specific verb plus resource plus a clear ranking criterion. It further distinguishes from siblings by explicitly excluding Shorts, making the tool's scope unambiguous.

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 use for view-based ranking of long-form videos, and the exclusion of Shorts hints at when not to use it. However, it never explicitly names alternatives like youtube_analytics_top_shorts or lists conditions for choosing this tool over others, so guidance is only implied.

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