douyin_unread_count

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

Annotations carry only a title, so the description bears the burden; it does disclose that the value is computed live from the comments API rather than a cached badge, and that results are bucketed per work. It does not mention login/auth requirements, latency from scanning works, or what the response object looks like. Adequate but thin for a tool with no behavioral annotations.

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?

Two short sentences, front-loaded with the definition, then the interpretive purpose. Every clause carries information — what is counted, how it is grouped, and that the figure is a real computed number rather than a decorative badge.

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?

There is no output schema, so the description should describe the return shape; "grouped by work" hints at structure but does not say whether it returns a total plus per-work counts or field names. For a very simple one-optional-param read tool this is close to sufficient, but the return contract remains implicit.

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 coverage is 100%, so the single `works` parameter (default 5, "扫最近几条作品") is already documented. The description mentions grouping by work but adds nothing about the tradeoff of increasing scan depth (cost/latency vs. accuracy) that would help an agent set the value. Baseline 3 applies.

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?

Names the specific resource and its shape: the count of comments awaiting reply, grouped by work ("待回复评论的条数（按作品分组）"). It also distinguishes itself from a raw badge by saying the number is computed from the comments API, which is a meaningful contrast to siblings like douyin_comments_list or douyin_notifications. It stops short of explicitly naming those siblings, so it is clear but not fully differentiated.

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 framing "这是\"该去回评论了\"的信号" implies the use case — a cheap triage check before deciding whether to open the full comment tools — but it never says when NOT to use it or names the alternative (e.g. douyin_comments_list) for actually reading or replying to comments. Usage is inferable rather than stated.

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