douyin_notifications

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

The only annotation is a title, so the description carries the behavioral load. It usefully discloses that the notification route does not exist and this is a surrogate, and that results are time-descending and filtered to unreplied comments from others — but it says nothing about auth/login requirements, failure modes when no works exist, or whether publishing a reply through douyin_comment_publish clears the flag.

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-loaded with the action first and the rationale second; every sentence is doing work, including the 404 explanation that pre-empts an agent hunting for a notifications endpoint. Only mild redundancy between '最近几条作品' and the works parameter.

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 does partially describe the return: comment records annotated as authored-by-others and unreplied, ordered newest-first. For a two-optional-parameter read tool this is close to sufficient, with the main gap being what fields each record contains and how login state affects results.

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% and both parameters already carry defaults and descriptions, including the 'more works = slower' cost hint. The description echoes the same scoping ('最近几条作品') without adding syntax, limits, or interaction effects, so the 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?

States a specific verb+resource: pull recent comments under my works, flag those from others that I haven't replied to, sorted newest-first. That scope ('my recent works' aggregated, not one video's comment thread) is what separates it from douyin_comments/douyin_comments_list, though the description never names those siblings directly.

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?

Usage context is implied rather than stated: 'for operations folks this is the part to handle first' suggests an inbox-triaging workflow, and the note that /notice and /messages are 404 justifies why this substitutes for notifications. But there is no explicit 'use X instead when Y' routing against douyin_comments_list, douyin_comment_replies, or douyin_unread_count, which overlap the same territory.

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