analyze_file

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

With no annotations, the description carries the full burden and does well: it enumerates the exact rule families and IDs executed (SEC001-012, COMPLEX001-005, STYLE001-005), so the agent knows the analysis is automatic and non-configurable, and it adds the important caveat that scores are a health reference, not an audit verdict. It still does not state that the operation is read-only or how it behaves on very large/unsupported files.

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?

Front-loaded with the one-line purpose, then bulleted rule families, then the return payload and the scoring caveat — every block is scannable and earns its place. The rule-ID enumeration is the longest element but is useful signal rather than filler.

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 no output schema, so the description must describe the return payload, and it does: language, code/comment/blank line counts, issues with rule id/severity/category/confidence/suggestion, and overall/security/maintainability grades A-F. It also frames the score's meaning, leaving nothing essential for correct invocation or result interpretation.

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 gives only a bare 'File Path' string with 0% description coverage, and the description compensates by specifying that the path may be relative to the project root or absolute. That is genuine added meaning beyond the schema, though no error behavior for invalid paths is described.

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 a specific verb+resource ('分析单个文件') and immediately narrows scope to a single file, which distinguishes it from the project-wide sibling check_project and the diff-oriented review_diff/review_changes. An agent can identify this as the per-file static analysis tool 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?

Scope ('单个文件') plus 'runs all applicable rules automatically' implies when this tool applies versus a project-wide scan, but no sibling is named and no when-not condition or prerequisite is stated. Usage is inferable rather than explicit.

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