搜索产品下的 Bug

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

注解已声明 readOnlyHint、idempotentHint 等，描述进一步补充了底层分页过滤机制和 scan_limit 对命中范围的影响，这些信息超越注解，帮助 agent 理解结果可能不完整以及如何调整。描述与注解一致，无矛盾。

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?

描述结构清晰，先概述功能，再列参数，最后给返回结构和注意事项。没有冗余信息，每个句子都提供价值，且关键限制（scan_limit）被突出。

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?

尽管没有输出 schema，描述明确给出了返回结构（{ product, keyword, scanned, matched, bugs }），注解覆盖了安全性，且参数说明完整。对于调用该工具所需的功能、参数、限制和返回信息，描述完整无缺。

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 覆盖了全部参数（100%），基线为 3。描述在 Args 中补充了 scan_limit 的默认值（200）和上限（1000），并解释了 keyword 匹配标题与 steps，这些细节提升了参数语义，因此评为 4。

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?

描述明确指出'在某产品下按关键词搜索 Bug（匹配标题与 steps）'，动词+资源+匹配字段清晰，与兄弟工具如 zentao_list_bugs（列出）和 zentao_get_bug（获取单个）有明显区分，不会混淆。

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?

说明了搜索场景（按产品、关键词）和底层实现（拉取分页后客户端过滤），并提示 scan_limit 限制及调大建议，提供了使用上下文。但未明确说明与 zentao_list_bugs 等替代工具的边界，缺少'何时不使用'的排除性指导。

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