ytdlp__get_video_comments_summary

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

No annotations are provided, so the description carries the full transparency burden. It discloses the return format and optional cookie/proxy/retry settings, but does not mention network dependency, potential failures, or the fact that 'summarize' appears to mean 'return a formatted list of top comments' rather than an AI-generated summary. This ambiguity is a significant 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 front-loaded with a clear purpose sentence, followed by a return-format remark and @param entries. The @param lines are necessary given the schema's lack of descriptions, but the wording could be tighter and the 'summarize' term is imprecise.

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 description covers purpose, return format, and all parameters, which is helpful for a 6-parameter tool with no output schema. However, it omits usage context, error/network behavior, and any distinction from sibling comment tools, leaving gaps that could confuse an agent deciding between tools.

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%, but every parameter is documented in the description with concrete constraints and defaults: URL scheme requirement, maxComments range, cookies file format, proxy example, maxRetries cap, and response mode default. This fully compensates for the bare schema and adds real meaning beyond parameter names.

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 states a specific action and resource: 'Fetch and summarize top comments from a video URL using yt-dlp.' It conveys the tool's main function and return type. However, it does not explicitly differentiate itself from the sibling tool ytdlp__get_video_comments, relying on the name 'summary' to imply the distinction.

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?

There is no guidance on when to use this tool versus alternatives such as ytdlp__get_video_comments. The description only explains what the tool does and its parameters, without any 'use this when' or 'instead of' context.

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