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

Annotations include readOnlyHint=false and destructiveHint=true, indicating a mutating operation. The description reinforces this with '高风险' and the preview/confirm mechanism. It discloses the preview-by-default behavior and that confirm=true is required for execution. However, it doesn't describe side effects like what happens to comments, or state changes beyond reactivation. Given that annotations already flag destructive and non-readonly, the description adds the confirm mechanism which is useful. But it doesn't go beyond that significantly, so a 3 is reasonable.

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: two sentences plus an args line. It front-loads the high-risk warning and the confirm default. The args list is a bit terse but clear. No waste, but the args line could be integrated into the main description for better readability. Still, it's efficient and structured well, earning a 4.

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?

The tool has no output schema, so the description should clarify return behavior. It doesn't mention what the preview shows or what the response after execution looks like. However, the context of a mutation tool with preview is partially covered by the confirm semantics. The required parameter id is documented. With four parameters all documented and the main behavioral note covered, it's adequate but missing output expectations and potential side effects, so a 3.

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 each parameter has a description. The description adds value by explaining the confirm parameter's role in the preview/commit flow and highlighting assignedTo as '重新指派给谁', which is a semantic hint beyond the schema's '重新指派给的 account'. The comment parameter is not elaborated but is self-explanatory. Since the schema already covers the parameters, and the description provides the critical confirm semantics, a 4 is justified.

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 states a clear verb ('重新激活') and resource ('已解决/关闭的 Bug'), distinguishing it from siblings like zentao_resolve_bug or zentao_close_bug. It specifies the action is a state transition to active, which is a distinct purpose. However, it doesn't explicitly name sibling tools it is not, so a 4 is appropriate rather than 5.

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 implies usage: when a bug is resolved/closed and needs reactivation. It includes the '高风险' warning and the confirm flow. It does not explicitly state when NOT to use it or mention alternatives (like zentao_assign_bug for reassignment), but the context of activation is clear. The guidance about '默认预览，confirm=true 才执行' is a clear usage instruction. A 3 is fair because it lacks explicit comparison with sibling tools.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, but the description adds valuable behavioral details: it is a high-risk operation, defaults to preview mode, and only executes with confirm=true. It also discloses that the comment parameter is silently discarded due to API limitations. This exceeds what annotations alone provide.

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 concise, with two clear sentences and a compact argument summary. It front-loads the action and risk warning, then adds the API caveat. It could be slightly more structured, but it is efficient and easy to parse.

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 destructive mutation tool with no output schema, the description covers the essential operational aspects: the preview/confirm gate, the comment limitation, the API endpoint, and the required parameters. An agent has enough information to call it correctly and avoid common pitfalls.

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 100%, so the schema documents all parameters. The description adds important semantic context: comment is explicitly marked as non-effective, confirm is explained as a preview/submit switch, and assignedTo is clarified as an account. This goes beyond the schema's basic 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 clearly states the action: '把 Bug 指派给某人' (assign Bug to someone) and specifies the underlying API call. It distinguishes from sibling tools like resolve, close, comment by focusing on assignment specifically. The title also clarifies status transition.

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 the high-risk nature and the preview/confirm pattern. It explicitly notes that comment is not effective, implying that a different tool (zentao_comment_bug) should be used for comments. However, it doesn't explicitly say 'use this tool when you need to assign' or contrast with alternatives, so it's not a full 5.

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

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

The description discloses the two-phase preview/commit pattern ('默认预览，confirm=true 才执行') and warns of high risk ('高风险'), which adds substantial value beyond the destructiveHint=true annotation. This aligns with the annotation and explains the critical safety gate an agent must respect. No contradiction with 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 tight: a one-line purpose, a risk warning, and a compact args listing. The risk and confirm behavior are front-loaded ahead of the redundant Args line. The Args line duplicates the schema but is short enough not to be wasteful.

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 destructive mutation with no output schema and no post-condition details, the description covers the critical confirm gate and risk profile well. It does not, however, describe what the response looks like, whether the state change is reversible, or what happens after closing – gaps an agent might need for a state-transition 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 100%, so all three parameters are already documented. The description's Args line largely restates the schema, but it does add semantic value by explaining confirm's meaning ('confirm=true 才执行' ties the flag to actual execution) and marks comment as optional. Baseline 3 is appropriate since the schema carries most of the load.

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 states a specific verb and resource ('关闭一个已解决的 Bug' – close a resolved Bug), which is clear about the action and target. It adds the nuance that the bug must be resolved first, helping distinguish from state-transition siblings like resolve, activate, and confirm. It doesn't explicitly contrast against siblings, so it loses a point, but the purpose is unambiguous.

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 precondition '已解决的' (resolved) implicitly tells the agent this tool is only appropriate after a bug has been resolved, which is genuine usage guidance. However, it never mentions when NOT to use it or names alternatives such as confirm_bug or resolve_bug, leaving sibling differentiation to inference.

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

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

The description discloses the critical behavioral trait: it will always return an error and will not simulate success. This goes beyond annotations (which don't indicate this) and is essential for the agent to avoid calling it. It also explains why (API limitation). Score 5.

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 front-loaded with the warning and alternatives, followed by the args. It's concise and to the point, though it repeats parameter names. Score 4.

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 that the tool is designed to fail, the description fully explains the failure mode and provides alternative actions. No additional information is needed for the agent to decide correctly. Score 5.

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 already provides descriptions for both parameters (Bug ID, 备注内容), and the description merely repeats them. The description adds no extra meaning beyond what the schema provides, so baseline 3 is appropriate.

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 tool attempts to add a comment to a bug, but immediately discloses that the API does not support this and the tool will return an error. This is a distinct purpose from siblings (which actually perform actions), so the agent knows it's a non-functional stub. Score 4 because it's clear but not a positive action.

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?

Explicitly states when NOT to use it and provides alternatives: use Web UI or old session API. This is exactly the guidance needed to route the agent away from this tool. Score 5.

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

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

The description discloses high-risk behavior and the default preview mode with confirm=true required for execution. This adds context beyond annotations: it explains the two-phase behavior (preview vs. actual mutation) and the effect (is_confirmed=1). Annotations already indicate destructive, but the description enriches understanding of the safety mechanism.

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 extremely concise: two short sentences plus a parameter list. It front-loads the purpose and risk, making it easy to scan. Every element earns its place with no redundant wording.

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 simple tool with three parameters, no output schema, and destructive annotations, the description covers the essential usage pattern (preview then confirm) and the effect. It doesn't mention return values, but that's not required given no output schema. The missing piece is guidance on when to use this tool instead of siblings, which is already penalized in usage guidelines.

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 100%, so the schema already documents each parameter. The description merely lists them (id, assignedTo?, confirm default false) without adding meaning beyond what's in the schema. The default false for confirm is already in the schema, so no additional value is provided.

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 states a specific action: confirming a Bug (is_confirmed=1). It clearly identifies the resource (Bug) and the effect (sets confirmation state). It distinguishes from siblings like resolve, close, assign by focusing on the confirmation action specifically.

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 no guidance on when to use this tool versus siblings like resolve, close, or assign. It only mentions the preview/confirm behavior, which is more about execution safety than tool selection. No explicit when-to-use or alternatives are stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, fully covering the safety profile. The description's '只读，不修改任何数据' merely repeats this annotation and adds no new behavioral context such as error cases, rate limits, or permission requirements. The only additional detail, the include_steps flag, is already described in the parameter schema.

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 well-structured, front-loading the core purpose and then providing a clear Args and Returns section. Every sentence earns its place, and the read-only note is a single short phrase. No fluff or redundancy.

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 read-only tool with comprehensive annotations, the description provides the essential return format (compensating for the lack of an output schema) and documents the optional parameter. It omits error handling or edge cases, but these are not critical for a safe read operation. It is complete enough for an agent to call it correctly.

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% for both parameters, and the description's Args section mirrors the schema exactly without adding new semantics. Per the baseline, when the schema fully documents parameters, a score of 3 is appropriate – the description adds no extra meaning beyond what's already structured.

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 '按 ID 获取单条禅道 Bug 的完整信息' – a specific verb (get) and resource (bug by ID) – and differentiates from siblings like zentao_list_bugs (list) and zentao_search_bugs (search) by focusing on a single bug retrieval. It also highlights the inclusion of reproduction steps, which is a distinct feature.

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 purpose implies usage when a single bug's full details are needed, and the read-only nature distinguishes it from write siblings (comment, resolve, close, etc.). However, it does not explicitly mention when to use alternatives like list or search, so it lacks explicit exclusions or alternative routing.

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

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.

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

Annotations declare destructiveHint=true and readOnlyHint=false, and the description adds critical behavioral context: it is high-risk, defaults to a preview, and requires confirm=true to actually commit. This goes beyond the annotation flags and informs the agent of the two-step safety mechanism, which is crucial for a mutation tool.

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 extremely concise: two short sentences plus a parameter list. The high-risk warning is front-loaded, immediately setting expectations. Every element serves a purpose, and the structure is easy to parse.

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 destructive tool with no output schema, the description covers the essential behavior (preview/commit), the resolution options, and defaults. It does not mention prerequisites like bug state, but given the annotations and schema, the agent has enough to invoke it correctly. Slightly more context on side effects could elevate it, but it is adequately complete.

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%, and the description essentially mirrors the schema's parameter documentation (enum values, defaults for resolvedBuild and confirm). It adds a compact summary but no new semantic information beyond what the schema already provides. Baseline 3 is appropriate.

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 tool marks a bug as resolved ('把 Bug 标记为已解决'), a specific verb-resource pairing that distinguishes it from sibling tools like close, activate, or confirm. The resolution enum list further specifies the possible outcomes, leaving no ambiguity about the tool's role.

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 a clear usage pattern: preview by default, commit with confirm=true, which is essential for a destructive operation. It does not explicitly compare with sibling tools or state when not to use it, but the context implies it is for the resolve action, distinguishing it from close or assign. The guidance is sufficient for an agent to decide when to call it.

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

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.