列出产品下的 Bug

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

Annotations already cover readOnly, idempotent, and non-destructive behavior. The description adds valuable context: server-side pagination and a warning that the returned 'total' may be inaccurate and should be cross-checked via actual pagination. This goes beyond annotations and helps the agent interpret results correctly.

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 structured with a clear summary, Args list, Returns, and a note. It is front-loaded with the core purpose and key details, though the Args list duplicates the schema and could be trimmed. Overall it is efficient and well-organized.

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 list tool with 5 parameters and no output schema, the description provides the return structure, pagination behavior, and a caution about the total field. It covers the essential operational aspects an agent needs, though it omits error handling or authentication details, which may be assumed.

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?

The schema has 100% parameter description coverage, so the baseline is 3. The description repeats the Args list but adds a nuance for assigned_to ('过滤当前页') and clarifies that status is optional (though the schema already does). It does not significantly enhance parameter understanding beyond the schema.

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 the verb (列出/list), the resource (Bug), and the scope (某产品下/under a product), making it distinct from siblings like get (single bug) and search (likely broader). It also mentions server-side pagination and optional filters, which further distinguishes its purpose.

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 explains how to use the tool (pagination, filters, read-only) but does not explicitly state when to prefer it over alternatives such as zentao_search_bugs or zentao_get_bug. The read-only and pagination details are useful, but no direct comparison or exclusion criteria are provided.

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