list_comments

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

With no annotations provided, the description carries the burden. It explicitly notes the tool is read-only ('只读'), which is a key behavioral trait. It also explains the order parameter values. However, it does not disclose pagination, return format, or any rate limiting, leaving gaps for an agent invoking the tool.

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 extremely concise – a single line with the core purpose, a parameter explanation, and a practical usage tip. It is front-loaded and every phrase earns its place. No wasted words.

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 simple list tool with three parameters and no output schema, the description is partially complete. It covers the order parameter and gives a usage context, but it omits explanation of the required url_or_bvid parameter, the page parameter, and the return format. An agent would need to infer the meaning of url_or_bvid from the tool name alone, which is not ideal.

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 must compensate. It explains the 'order' parameter ('hot=热门, time=最新') but provides no meaning for 'url_or_bvid' or 'page'. The required parameter 'url_or_bvid' is left completely unexplained, and 'page' is ignored. This is insufficient given the lack of schema descriptions.

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 '视频评论区（只读）' which clearly identifies the resource (video comments) and implies the action (listing). It distinguishes from siblings like subtitles or video info. However, it does not explicitly state a verb like 'list' or 'fetch', relying on the tool name for the action, so it falls short of a 5.

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 provides a usage hint: '高赞评论常含勘误与补充，做笔记前值得看' – suggesting the tool is useful before taking notes. It does not explicitly mention alternatives or when not to use it, nor does it contrast with sibling tools. This is implied guidance rather than explicit direction.

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