repair_propose_batch

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

The description claims the tool is "read-only, never writes data," but the annotations set readOnlyHint=false, which indicates the tool may modify state. This is a direct contradiction between the description and structured 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 compact, front-loads the core purpose, and includes only relevant information: scope, read-only intent, issue_ids behavior, and return contents. There is no 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?

The description covers the return shape in the absence of an output schema and explains the issue_ids default. However, it omits any comparison to sibling repair tools and contradicts the readOnly annotation, leaving important context incomplete.

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 67%, and the description mainly repeats the schema's own issue_ids default behavior. It adds no meaning for scan_run_id or source_path, leaving two parameters without descriptive semantics beyond the minimal schema entries.

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: "Generate repair proposals" for issues of a scan run. It distinguishes this from sibling tools like repair_apply_batch, repair_rollback_batch, and repair_verify by clarifying that it only proposes and never writes data.

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 guidance on the issue_ids parameter, including that omitting it covers all issues of the run. However, it does not explicitly say when to choose this tool over alternatives such as repair_apply_batch or repair_verify, leaving the workflow context implied rather than stated.

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