Change Review

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

There are no annotations, so the description must carry the behavioral burden. It discloses what each action produces—modified symbols, must-read files, tests to run, contract signals, blind spots, blast radius, downstream callers, and change risk—and mentions automatic token compression. It does not explicitly state read-only behavior, but the analysis/review framing strongly implies it.

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 well-structured with a punchy lead sentence, action bullets, and explicit replacement topic. However, the Usage short and Usage long sections partially repeat the same guidance, and the REPLACES paragraph is slightly redundant with the opening line.

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 no output schema and no annotations, the description does a good job of covering all three action modes and their outcome categories, plus when to invoke the tool. It is slightly weakened by not explaining exactly how the diff/commit-range/file-list input is provided, since no input parameter exposes it.

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 100%, but the description adds substantial semantic value beyond the bare 'action' property by explaining what each enum value does. It also links compress_payload to the token-compression behavior and describes the high-level result categories agents can expect, which helps parameter selection.

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 begins with a specific verb and resource: 'analyses and reviews proposed changes' via diffs, commit ranges, chunk lists, or file lists. It further clarifies the three concrete action modes and explicitly distinguishes itself from alternatives like git diff, manual diff review, and grep_search.

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 says 'REPLACES: git diff, manual diff review, grep_search' and tells the agent to use this tool 'instead of these alternatives'. It also gives situation-specific guidance: use after making changes to verify safety, or before merging to assess risk, plus when to inspect commit/branch diffs or before refactoring.

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