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

Annotations already declare idempotentHint=true, readOnlyHint=false, and destructiveHint=false; the description's '记录' is consistent with a non-destructive, idempotent write. It adds the choice vocabulary but does not disclose side effects, such as whether a queued choice or immediate switch changes state beyond recording.

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 entire description is one sentence, front-loaded with the action and resource, followed by a compact enumeration of options. There is no filler 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?

The tool is simple, output schema exists, and annotations cover the safety profile, so the description need not explain return values. Still, the absence of explicit sibling differentiation and exact parameter formats leaves moderate gaps for an agent selecting and invoking the tool.

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?

With schema description coverage at 0%, the description must carry parameter meaning. It does convey that 'reference' is the external reference and 'choice' is one of the three listed options. However, it does not specify exact accepted string values or the format of the reference.

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 uses a specific verb '记录' and identifies the resource: the user's choice about an external reference, with three concrete alternatives. It clearly states what the tool does, though it does not explicitly name sibling tools or contrast them.

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?

No guidance is given about when to use this tool versus report_write_decision or review_queue_* tools. The intended context is implied by the phrase '用户对某个外部引用的选择', but no explicit when-to-use or when-not-to-use instructions 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is established. The description adds the scope ('current repository') and the two return values (path and last update time), which is useful context beyond the structured annotations. However, it does not elaborate on behavior like whether multiple reports are returned or if the path is a directory or file. Given the annotations cover safety, a 3 is appropriate.

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 a single, compact sentence in Chinese that directly states the resource and the returned data. There is no fluff, and the key information is front-loaded. It is appropriately sized for a zero-parameter informational tool.

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 zero-parameter tool with an output schema, the description adequately covers the core purpose. It mentions both the path and the update time, which are the likely output fields. However, it does not clarify whether 'report' refers to a specific file or a directory, or whether multiple reports are handled. Given the low complexity and presence of an output schema, the description is mostly complete but leaves a small ambiguity.

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 tool has zero parameters, and the schema is empty with 100% schema_description_coverage. The description's mention of 'report file path' and 'last update time' aligns with the expected output, and there is no parametric ambiguity to resolve. A baseline of 4 for zero-parameter tools is warranted, and the description adds value by framing the return data.

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 resource ('report file path') and the information returned ('last update time') in the current repository. It clearly differentiates from siblings like report_write_decision or report_external_choice, which involve writing or choice-making. An agent can understand the tool's purpose without opening the schema.

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?

There is no guidance on when to use this tool versus alternatives. The description is purely declarative and does not mention exclusions, prerequisites, or relationships with sibling tools (e.g., report_write_decision or review_read). An agent must infer that a path/timestamp query is intended for finding report files, but no explicit routing is 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?

The description's 'update' aligns with annotations (readOnlyHint=false, idempotentHint=true). It does not add behavioral context beyond what annotations already provide, such as overwriting existing content or any side effects. With annotations covering mutation and idempotency, the description adds minimal extra value.

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 a single, concise sentence that front-loads the action and scope. No wasted words, and it conveys the essential information in minimal space, making it 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?

Given the tool has no required parameters and an output schema exists, the description is still thin. It lacks usage guidance, parameter details beyond a high-level mapping, and any mention of side effects or prerequisites. For a mutation tool with several siblings, this is insufficient for an agent to select and invoke 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 coverage is 0%, so the description must clarify the parameters. It maps 'intro' to '简介' (introduction) and 'key_points' to '重点' (key points), which provides some semantic grounding. However, it doesn't explain the format or constraints beyond the schema's basic types, leaving some ambiguity about how key_points should be 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 the action: updating the report header's introduction and key points. It specifies the resource (report header) and the fields involved, which helps distinguish it from sibling write tools that likely modify other report aspects. However, it doesn't explicitly name alternatives or contrast with them.

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?

No guidance is provided on when to use this tool versus sibling write tools like report_write_decision or report_write_fix. The description only states what it does, leaving the agent to infer the appropriate context. Given the many sibling tools, this is a notable gap.

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 convey that this is a non-read-only, idempotent, non-destructive operation. The description adds that it records a user decision and a subsequent better-handling suggestion, which aligns with the idempotentHint. It does not detail whether existing decisions are overwritten, appended, or versioned, but annotations lower the burden and there is no contradiction.

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 a single dense sentence with the purpose front-loaded and no filler. The parenthetical slash-separated list is somewhat hard to scan, but every part contributes meaning and the length is appropriate.

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 4-parameter tool with an output schema and informative annotations, the description covers the core workflow and the two central parameters. It is incomplete regarding the plan parameter and the boundary with report_write_fix, but an agent can still infer a reasonable call.

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 0%, so the description must compensate. It partially does: user_decision is clarified by the decision facets, better_handling is echoed as '更有效处理建议', and finding_id is implied by '某条发现'. However, the plan parameter is not explained, and the exact expected value format for user_decision remains vague.

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 uses a concrete verb ('记录/record') and a specific resource ('用户对某条发现的决定' / user decision on a finding), and it enumerates the decision facets stored (fix/risk/no-fix consequences/immediate or planned/authority). It is clearly distinguishable from siblings such as report_write_fix, though it does not explicitly contrast itself with them.

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 phrase '用户决定之后' gives clear temporal context: the tool is used after the user has made a decision and to log the AI's follow-up handling suggestion. However, there is no explicit guidance on when not to use it or which sibling should be chosen instead, leaving some inference to the agent.

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 mark the operation as non-read-only, idempotent, and non-destructive. The description adds a meaningful business rule—'没有回滚点的修复不予记录' (fixes without a rollback point will not be recorded)—which extends the schema's required constraint into a behavioral guardrail. It does not contradict the annotations and adds useful context about how the tool enforces rollback_point.

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?

Two tight sentences with the purpose front-loaded and the mandatory-rollback constraint placed right after. There is no filler or redundancy; every phrase adds information.

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 13-parameter write tool with zero schema descriptions and 12 required parameters, the description is a useful but partial skeleton. It does not explain how the target report is identified via the required 'file' parameter, nor the roles of 'review_content' and 'fix_content'. Since an output schema exists, return values need not be described, but the ambiguity around 'file' and the lack of usage guidance are notable gaps.

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?

With 0% schema description coverage, the description compensates by giving natural-language meaning to many parameters: '修复前后差异' for before/after, '风险级别' for risk_level, '是否脚本' for has_script, '是否成功' for fixed_ok, '不修复后果' for consequence_if_not_fixed, '立即/计划' for execution, '权威性' for authority, and '回滚点' for rollback_point. It notably clarifies the expected values of execution. However, it omits file, review_content, fix_content, and finding_id, leaving them to title inference.

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 opens with '把一次修复写入报告' (write a fix into the report), a clear verb–resource statement, then enumerates what the fix record contains. It is unambiguous that this tool records a fix entry, but it does not explicitly contrast itself with sibling report_write_decision or rollback_create, so differentiation is largely implicit.

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?

Usage context is implied: an agent can infer this tool is for recording fixes, and the rollback_point requirement suggests when it applies. However, the description never names alternatives, exclusions, or conditions such as 'use report_write_decision for decisions' or 'use rollback_create to create a rollback point first.'

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 annotations declare readOnlyHint=true and idempotentHint=true, but the description says the tool '写入报告' (writes into a report), which implies a side effect beyond reading. This directly contradicts the read-only annotation. The description also does not clarify whether this report write is persistent or merely part of the response, so the behavior is misleading.

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 a single dense sentence with no filler, and it front-loads the primary listing action. However, the three-part behavior (scan, write report, provide prompt) is packed into one long clause, and splitting it would improve readability without adding length.

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?

An output schema exists, so return-value details do not need to be in the description, and the annotations cover safety. Still, the contradiction between read-only annotations and the report-writing behavior leaves an unresolved gap, and the description does not say how the three-choice prompt is determined or when not to use this tool. It is adequate but not 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?

There are zero parameters, so the input schema already covers the full parameter surface. Following the 0-params baseline, the description does not need to add parameter-level semantics.

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: list references in the current repository that point to other repositories, folders, environment-variable paths, or git addresses. It also clarifies the expected outputs: writing a report and providing a three-choice prompt that must be relayed verbatim. This is specific enough to distinguish the tool from broader siblings like review_scan or review_secrets_inventory.

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 clear context for when this tool applies: reviewing the current repository's external path references. It also provides an explicit usage instruction: the three-choice prompt must be passed to the user verbatim. It does not name alternatives or exclusion conditions, but the scope is clear enough to guide selection.

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, covering the safety profile. The description adds the behavioral detail that it checks whether the SHA256 matches a recorded hash from a report, which is useful context. However, it does not explain what happens on mismatch, whether it returns a boolean or a detailed report, or any other side effects, so it adds limited value beyond 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 a single, compact sentence that efficiently lists the metadata attributes and the consistency check. It is well-structured and front-loaded with the core purpose. No filler or redundant content.

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?

An output schema exists, so return value details are not required. However, the description lacks information on the input format and does not explain when this tool should be preferred over siblings. For a tool with one parameter and a clear purpose, it is mostly complete, but the missing usage context and input clarification lower the score.

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 0%, so the description must fully explain the parameter. It only says 'file' without specifying the expected format (e.g., path, identifier, or URI). The description implies the file's metadata is reviewed but does not clarify how the file is referenced. This is insufficient given the low schema coverage.

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 reviews file metadata including dates and SHA256 hash, and checks consistency with a recorded hash. It uses a specific verb ('review') and resource ('file metadata'), making the purpose unambiguous. However, it does not explicitly distinguish itself from sibling tools like review_read or review_scan, so it misses the top score for sibling differentiation.

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 alternatives. It does not mention conditions, prerequisites, or exclusions. With many sibling tools (review_open, review_read, review_scan), an agent would need to infer when metadata review is appropriate, which is not clearly conveyed.

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 and destructiveHint=false, ensuring the agent knows it's safe. The description adds valuable behavioral context: it performs a read-only review, automatically switches to a new report file when the repository changes, and explicitly states it does NOT read README or textual introductions. This goes beyond the 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 concise, one sentence, and front-loaded with the core action ('进入一个文件夹开始只读审查'). However, it packs multiple actions into one sentence, which could be better structured but remains dense and efficient.

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?

There is an output schema (though not detailed in the prompt), so the description doesn't need to explain return values. Given the tool's complexity (multiple steps), the description covers key aspects: read-only, repo detection, file inventory, big project check, and repo change handling. It lacks details on error handling or edge cases, but is adequate for agent use.

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 0%, meaning the description must compensate. It mentions 'path' implicitly ('进入一个文件夹' - enter a folder) and provides context on usage. However, it does not specify the path format, whether it's absolute or relative, or any constraints. Since there is only one param, the baseline is 4, but the description doesn't fully clarify semantics, so 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's purpose: enters a folder to begin a read-only review, with specific actions like identifying the repository, inventorying actual files, and checking if the repository changed. It distinguishes itself from siblings like review_scan and review_read by describing the initial open/inventory step.

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 when to use this tool: at the start of a review to open a folder assess its content(migrations), and mentions automatic switching to a new report if the repository changeswf. It does not explicitly say when not to use it or name alternatives, but the context is clear enough for an agent to know this is the entry point.

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=false, destructiveHint=false, and idempotentHint=true, so the safety profile is available. The description adds that the item is external and queued for planned review, but says nothing about validation, duplicate handling, or side effects. It does not contradict the 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?

One sentence, front-loaded with the action and target, with no filler. It is efficient and every clause contributes to understanding the tool's purpose and trigger.

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 tool with two simple parameters and an output schema, the description covers the core action and trigger but leaves path/note semantics unaddressed and does not explain how adding relates to review_queue_list or review_queue_next. Given 0% schema coverage, this is a meaningful gap.

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 0%, so the description must compensate for undocumented parameters. It only implies that path refers to the external repository/folder; the note parameter is entirely unexplained. The description adds minimal meaning beyond the schema's raw property names.

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?

Description uses a specific verb ('add') and resource ('external repository/folder') and names the target list ('planned review list'), which distinguishes it from siblings like review_queue_list and review_queue_next. The trigger clause 'user selects 1' reinforces its role. It is unambiguous about what the tool does.

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 phrase '用户选 1 时调用' gives an explicit trigger condition for when to invoke the tool. It does not mention alternatives or exclusions, but the context is clear enough to avoid confusion with related queue 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds no extra behavioral context such as ordering, filtering, or return format, but for a simple list operation this is acceptable. 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 a single, concise sentence that directly conveys the action and resource. It is front-loaded and contains no fluff, though it is minimal and essentially restates the tool name.

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, zero parameters, and existing output schema, the description is adequate but sparse. It does not explain what constitutes a 'planned review' or how the list is organized, but the output schema likely covers return details. For a straightforward list tool, this is minimally sufficient.

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 tool has zero parameters and the schema coverage is 100% (empty properties). The description correctly omits parameter details since there are none. No additional parameter semantics are needed.

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 (view) and resource (the planned review list). It is distinguishable from siblings like review_queue_add or review_queue_next, though it doesn't explicitly contrast with them. 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?

There is no guidance on when to use this tool versus alternatives such as review_queue_next or review_open. The description provides no context about the role of this tool in the review workflow or when it should be preferred over siblings.

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 a non-read-only, non-destructive, idempotent operation. The description adds useful context: it only marks/takes out without entering, and requires an authorization reminder before proceeding. It does leave what 'marking' entails and how the queue advances somewhat ambiguous, but the main side-effect boundary is clear.

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?

A single concise sentence, front-loaded with the primary action, followed by a clarifying limitation and a direct next-step instruction. No filler or redundant content.

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 zero parameters, an output schema, and strong annotations, the description covers purpose, side effects, and the follow-up call. It does not specify whether the item is removed from the queue or how 'next' is ordered, but that is a minor gap for such a simple fetch tool.

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?

There are zero parameters and schema description coverage is 100%, so the baseline is 4. The description adds no parameter-specific details, but none are necessary.

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 ('取出下一个待审路径') and identifies the resource, a pending-review path. It also clarifies that this tool does not automatically enter, which clearly distinguishes it from the sibling review_open.

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 explicitly maps the workflow: use this tool to take out and mark the next pending path, remind the user about authorization, then call review_open to actually open it. This tells the agent exactly when to use this tool versus the alternative review_open.

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. The description goes beyond this by adding a critical behavior: content is wrapped in an untrusted_content envelope and must be treated as data, not instructions. It also reinforces the read-only nature ('只读取'), making behavior clear.

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?

Two short sentences with no filler. The core operation is front-loaded, and the security note about untrusted_content earns its place. Every sentence adds value.

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 read-only tool with annotations covering safety and an output schema present, the description is nearly complete: it specifies scope, line-range targeting, and the untrusted-content handling. It only lacks explicit usage guidance versus sibling tools, but this is minor given the low complexity.

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?

With 0% schema description coverage, the description must compensate. It adds meaningful context by identifying 'file' as a file in the current repository and 'start'/'end' as a line range. However, it does not explain defaults, inclusivity, or boundary behavior, so parameter understanding is only partially covered.

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 ('只读取' – only reads), a specific resource ('当前仓库内某文件的指定行段' – a specified line range of a file in the current repository), and an intended purpose ('供解释用' – for explanation). This clearly distinguishes it from siblings like review_open and review_scan, which have different scopes.

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: use this when you need read-only access to a line range of a current repo file for explanatory purposes. However, it does not explicitly name alternatives or state when NOT to use it, leaving 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that it 'writes to report' and returns detailed structured findings, which is useful context. However, it does not disclose potential side effects of report writing or any permission requirements, and the report-writing behavior is not fully clarified beyond the annotation.

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 a single sentence that front-loads the main action, then explains parameter semantics, then outlines return structure. It is dense but efficient, with no redundant filler. Every clause adds value, and the structure is logical.

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 existence of an output schema and comprehensive annotations, the description is nearly complete. It covers the action, parameters, and return values. It lacks explicit guidance on when to use this tool versus siblings and any error or edge-case handling, but these are secondary given the rich annotations and output schema.

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 0%, so the description carries the full burden. It explicitly explains that 'offset/limit are file sequence numbers' (not line numbers) and that an empty path scans the root directory. This gives crucial meaning to all three parameters, which are otherwise undocumented in the schema. The description fully compensates for the lack of schema documentation.

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's purpose: 'Batch scan line by line according to file list' and specifies the scope (when path is empty, scans repository root). It also enumerates the structured findings returned and notes that it writes to a report. This is a specific verb+resource description that distinguishes it from generic scanning tools.

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 context on path behavior ('when path is empty, scan current repository root') but does not explicitly state when to use this tool versus alternatives like review_open or review_read. There is no mention of prerequisites or conditions that would lead an agent to choose this tool over siblings.

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, idempotentHint, and destructiveHint=false. The description adds that it does not output secret values, that it returns specific metadata (dates, git tracking, reference count, decommission judgment), and instructs the agent to pass full paths to the user. This goes beyond annotations without contradiction.

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?

Two sentences: the first defines scope and output fields, the second states the no-secret-value rule and the user-relay instruction. No filler, information-dense, and front-loaded. Every 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?

For a read-only inventory tool with one optional parameter and an output schema, the description covers scope, output fields, exclusions (no secret values), and user instructions. It is sufficient for an agent to invoke it correctly without additional context.

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 0%, so the description must explain the parameter. It mentions '可选含已纳入的用户级配置目录' (optionally include the already-included user-level config directory), clarifying the effect of include_user_level. It could be more explicit about the parameter name and default, but it does add meaning 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 it lists secrets, private keys, credentials, and environment variables in the current repository (optionally including user-level config), and enumerates the output fields (full path, file name, line number, variable name, dates, git tracking, ignored status, reference count, decommission judgment). It also explicitly notes it does not output secret values. This is specific and distinct from siblings like review_scan or review_read.

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 its use for secrets inventory and mentions the optional user-level config inclusion, but does not explicitly contrast with sibling tools or state when not to use it. It does instruct the agent to relay full paths to the user for verification, which is a usage guideline. Lacks explicit alternative routing but is not misleading.

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 provide readOnlyHint, idempotentHint, and non-destructive hints. The description adds useful behavioral details beyond those: it batches by offset/limit, treats skill/rules/mcp.json/hooks as untrusted, and writes results to _用户级配置.md. The report-writing mention is consistent with the tool's purpose and does not materially contradict the read-only annotation.

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 every sentence earns its place: scope, whitelist boundary, batching, trust assumptions, and output report. It is front-loaded with the resource being reviewed and contains no filler or repetition.

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 description provides most actionable details: target directories, scan boundary, batching behavior, trust assumptions, and output report name. But the undocumented extra_paths parameter and the lack of explicit sibling-tool routing leave a meaningful gap for a fully informed invocation.

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 description explains offset/limit as path batching and gives whitelist context, which adds meaning beyond the raw schema. However, extra_paths is not described at all, and schema description coverage is 0%, so the meaning, format, and relationship of extra_paths to the whitelist remain unclear.

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 uses a specific verb ('审查') and identifies a concrete resource: user/program-level AI assistant and editor configs, backed by explicit directory examples (~/.cursor, ~/.claude, /opt, etc.). It is clearly distinguishable from the more general review_scan tool, though it does not explicitly name or contrast any sibling tool.

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 a clear scope boundary: only scan whitelisted paths that actually exist and do not traverse the whole disk. It also specifies batching via offset/limit. However, it does not explicitly state when to prefer an alternative sibling tool, so it stops short of full routing guidance.

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 readOnlyHint=false (writes), destructiveHint=false (safe), and idempotentHint=true. The description adds meaningful context: files are backed up, stored outside the repo, and the name is pinned in the report. This goes beyond the annotations and clarifies the non-destructive nature. It does not contradict 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 a single sentence, concise and front-loaded with the directive 'Call before modifying any files.' It contains no fluff, but it is a bit dense and could benefit from separation of the report-pinning aspect. Overall, it is efficient.

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 description covers the core action, storage location, and reporting integration. An output schema exists, so return values are documented elsewhere. Missing details include behavior on repeated calls (though idempotent hint covers that) and the purpose of the 'note' parameter. It is adequate for an agent to invoke 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 0%, so the description must explain parameters. It mentions 'these files' for the files parameter, but does not explain the 'name' and 'note' parameters at all. The description says 'named rollback point' so name is implied, but note is completely unexplained. This is a significant gap given zero schema documentation.

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's function: back up files into a named rollback point before modification, stored outside the repository, and pin the name in the report. It distinguishes itself from rollback_list and rollback_restore by its specific verb 'back up' and explicit context of pre-modification.

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 an explicit trigger condition: 'Call before modifying any files.' It does not explicitly mention alternatives or when not to use, but the context of siblings and the directive are clear. It could be improved by noting that rollback_restore is for restoring, but that's not necessary.

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 and destructiveHint false, so the description adds value by specifying the scope ('current repository') and completeness ('all' rollback points). It does not contradict annotations and provides useful contextual detail.

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?

A single, front-loaded sentence with no filler. It states the action, resource, and scope efficiently, earning every word.

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 parameterless list operation with an output schema, the description fully captures the operation's scope and purpose. There is no missing information an agent would need to invoke 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?

With zero parameters, the schema trivially covers everything. The description adds no parameter-specific information, but none is needed. The baseline for 0 params is 4, which is appropriate here.

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' and the resource 'rollback points' scoped to the current repository. It distinguishes itself from siblings like rollback_create and rollback_restore by focusing solely on listing existing rollback points.

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 when to use it (when you need to see available rollback points) but does not explicitly mention alternatives or exclusion criteria. Since the purpose is self-evident, it meets the 'implied usage' bar but lacks explicit 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 mark destructiveHint=true, but the description adds that it overwrites specific files and mandates a user-authorization confirm string, providing behavioral context beyond the annotation.

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?

A single concise sentence that front-loads the core action and the critical confirm requirement, with no redundant words.

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 description covers the destructive effect and the mandatory confirm safeguard; the presence of an output schema handles return values, so nothing essential 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?

With zero schema description coverage, the description fully explains the 'name' parameter as the rollback point and provides a precise template for the 'confirm' parameter, making parameter usage unambiguous.

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 of restoring a named rollback point and explicitly notes that it overwrites repository files, which differentiates it from sibling tools like rollback_create and rollback_list.

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 specifies the required confirm parameter with an exact format, giving a clear usage condition. While it does not explicitly name alternatives or exclusions, the scope is well implied by the action.

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