Scan repository files in batches to identify risky code, secrets, and untrusted configs, returning structured findings with file paths, line numbers, and remediation guidance.
按文件清单分批逐行扫描（offset/limit 是文件序号）。path 为空时扫描当前仓库根目录。 返回结构化发现（含文件详细路径、文件名、行号、代码、中文直译、白话、后果、处置、权威依据），并写入报告。
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | ||
| limit | No | ||
| offset | No |
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Changes observed during successful MCP inspections.
v0.1.0Does 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.