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

Adds substantial context beyond the readOnly/idempotent/openWorld annotations: a hard cap of 100 top-level comments, exclusion of commenter names/handles/channel IDs, the fact that comments-off videos and errors are not charged, the x402 USDC-on-Base price per successful call, and the PaymentRequired object returned when called unpaid. This is exactly the payment and authorization information annotations cannot convey.

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?

Front-loads the trigger condition before the output inventory, pricing and error semantics, so the highest-value information lands first. Dense but nearly every clause carries load; only the field enumeration is slightly list-heavy.

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 no output schema, the description carries the full return-value burden and does so: it names the returned fields, the volume cap, the deliberate omission of commenter identity, and the total count. Pricing, non-charging behavior and the PaymentRequired fallback cover the remaining gaps for a paid open-world tool.

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 the schema already documents lang, sort, limit, video and country – the baseline for this dimension. The description corroborates the limit range ('up to 100 top-level comments') and clarifies that replies are not returned, but adds no syntax or format meaning for the remaining parameters.

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?

States a specific resource (top-level YouTube comments on a video) and enumerates exactly what comes back: text, like count, reply count, relative publish time, pinned/by-creator flags, total comment count. An agent can distinguish it from youtube_video, youtube_transcript and youtube_channel without opening any schema.

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?

Opens with an explicit trigger ('Use when you need what viewers say about a YouTube video') and lists concrete use cases such as sentiment, feedback mining, FAQ and product research. It stops short of naming alternatives (e.g. use youtube_transcript for spoken content), so routing across siblings still requires inference.

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