热门划线

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

Beyond the existing readOnlyHint=true and destructiveHint=false annotations, the description adds valuable behavioral details: fixed 20-item response, no pagination, sorting by popularity, and the exact returned fields (`markText`, `items[].totalCount`). This materially helps an agent predict behavior and is consistent with the 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?

The description is compact and front-loaded: the first sentence states the core purpose and fields, and the second explains critical server-side limits. The cross-reference to `get_highlight_reviews` adds useful integration guidance with no filler.

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?

Given the rich annotations, full schema coverage, and presence of an output schema, this description is nearly complete. It adds the critical no-pagination and top-20 behavior plus a cross-tool usage hint. The only missing element is an explicit comparison with sibling highlight tools, which is a minor gap.

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?

All three parameters are already fully documented in the schema (100% coverage), so the baseline is appropriate. The description does not add meaningful input-parameter semantics beyond what the schema already provides; its `items[].range` mention concerns output, not 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?

The description clearly states a specific verb and resource: '获取书籍/章节的热门划线' with the endpoint `/book/bestbookmarks`, and clarifies it is sorted by popularity. However, it does not explicitly contrast itself with sibling tools like `get_book_highlights` or `get_chapter_underlines`, so differentiation is left mostly to the name and inferred meaning of '热门'.

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 operational context but no explicit when-to-use versus alternatives. It mentions that the server always returns the top 20 items, does not support pagination, and that `items[].range` can be passed to `get_highlight_reviews`; the choice of when to use this tool instead of a sibling is implied rather than stated.

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