Retrieve topics in a specified category with pagination. Returns total topic count, current page list, and next-page flag using category_id and optional page number.
列出指定类别下的话题（每页约 30 条）。返回含该类别总话题数 topic_count、 本页话题列表与是否有下一页。category_id 用 list_categories 查询。每条话题已含 category、min_trust_level。展示约定同 latest_topics（Markdown 表格、完整标题、 纯文字表头禁用 emoji）。
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| category_id | Yes |
Changes observed during successful MCP inspections.
v0.2.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses pagination (about 30 per page), return structure (topic_count, list, next-page flag), and topic fields (category, min_trust_level). It also specifies output formatting (Markdown table, full title, no emoji). This goes beyond a bare description, but it omits edge behavior (e.g., empty category, invalid ID) and does not explicitly state read-only nature, though it is implied.
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 organized into short clauses that each add distinct value: purpose, return behavior, parameter lookup, topic content, and formatting rules. It is front-loaded with the core action and avoids redundancy. Slightly verbose in listing display details, but each sentence earns its place.
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 tool's simplicity (2 integer params, no output schema, no annotations), the description covers most operational needs: what it returns, how to get the required parameter, and display format. The main gap is the undocumented 'page' parameter and any error/empty-state behavior. Overall, it is fairly complete for a listing operation.
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 0%, so the description must explain parameters. It clarifies category_id by instructing to query it via list_categories, but it does not describe the 'page' parameter at all—its role, defaults, or bounds. One of two parameters is left unexplained, which is a significant gap for a tool with zero schema 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 explicitly states '列出指定类别下的话题' (list topics under a specified category), giving a clear verb and resource scope. It further distinguishes the tool by detailing the return payload (topic_count, topic list, next-page flag) and referencing display conventions from latest_topics, so an agent can differentiate it from siblings like tag_topics or latest_topics.
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 gives context on how to obtain category_id via list_categories, implying the tool is used when a category is known. However, it does not explicitly state when to prefer this over alternatives (e.g., tag_topics, latest_topics) or provide negative usage conditions. It offers some guidance but not exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.