rank_list

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

With no annotations, the description carries the burden and does substantial work: it discloses that results are paginated with a cursor, that each page carries that day's category tree, and — importantly — that image/video/audio come back as short refs (img:12, video:3) that are only valid for the lifetime of the current MCP run and must be routed through image_view. It stops short of stating permission requirements or that no state is mutated, though '读取' implies a read.

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?

Purpose and content list are front-loaded, then filtering, then cross-tool routing, then return-value semantics — a logical order with no filler sentences. It is dense and long, but nearly every clause carries information an agent needs; the only soft spot is the slightly sprawling category parenthetical.

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 12-parameter tool with no annotations and no output schema, the description compensates well by describing the returned fields and the ref-based media handling. Gaps remain around pagination termination and what the response envelope looks like (next_cursor is only named inside the schema), but nothing critical for calling it correctly is missing.

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 100%, so date, count, cursor, rank_type, categories and the rest are already documented in the schema, including the 'take next_cursor' and 'take categories from the previous page' rules. The description reinforces the category hierarchy idea (level 1 大类 vs level 2 细类) but adds no new syntax or constraints beyond what the schema states, so 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?

The description names a specific verb and resource — paginated reading of a 排行榜 — and enumerates the returned fields (名次、effect_id、等级、投稿量、跟拍量、热玩分…). It explicitly separates itself from rank_subjects for topic-based boards and from works_by_effect for drilling into one effect, so an agent can distinguish it from the many rank_* siblings.

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?

It gives clear routing for two cases: subject/topic boards go to rank_subjects, and inspecting a specific effect's project goes to works_by_effect. It does not, however, say when to pick this over rank_hotspots or rank_innovation, so the alternatives guidance is partial rather than exhaustive.

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