fetch_comments

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

No annotations are provided, so the description carries the full burden. It adds useful context by stating it does NOT generate notes ('不生成笔记') and by outlining the return structure (including an error field). However, it does not explicitly disclose read-only behavior, authentication requirements, rate limits, or how errors are surfaced beyond the error field. It is moderately transparent but leaves some behavioral aspects unspecified.

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 concise: three sentences that front-load the main purpose, followed by the return format and usage guidance. Every sentence provides value, with no filler. The structure aids quick comprehension.

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?

Despite lacking parameter semantics, the description gives a strong sense of the tool's role within the ecosystem (preview for notes, alternative to danmaku, injectable into prompts) and includes the return format. Since an output schema exists, the return values are covered elsewhere. The tool has only 2 parameters, and the description is reasonably complete for its complexity, though it could be rounder with explicit parameter explanations.

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%, and the description does not explain the parameters. It references video indirectly ('视频' in the first sentence) but does not clarify the 'limit' parameter or its default behavior. The description adds little beyond what the schema already shows, failing to compensate for the lack of parameter 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 clearly states the tool's purpose: '抓取 B 站视频的热门评论' (fetch hot comments from Bilibili videos). It specifies the resource (B站视频), the action (抓取/fetch), and the scope (热门评论/hot comments). It also distinguishes itself from sibling tools by explicitly saying it does not generate notes, and references fetch_danmaku and generate_note as alternatives.

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 mentions the intended use case: '供生成笔记前预览/参考' (for preview/reference before generating notes). It also points to alternatives: '可用 fetch_danmaku 看弹幕汇总' (use fetch_danmaku for danmaku summaries) and 'generate_note 的 include_comments' for injecting both into note prompts. This provides clear when-to-use and when-to-use-other tools guidance.

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