report_write_fix

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.