pre_merge_review

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

Goes well past the annotations by disclosing the payment model (x402 over Base, requires AGENT_PRIVATE_KEY, capped by MAX_USDC_PER_CALL), the exact price, and the billing atomicity guarantee ('charged only when every member succeeds'). Annotations only say it is non-read-only, open-world and non-idempotent; the description supplies the operational context an agent needs before spending money. Pricing arithmetic is internally consistent ($0.75 × 0.8 = $0.60).

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-loads the identity and the input/output contract in the first sentence, then the bundle composition and savings, then cost. Dense but nearly every clause carries decision-relevant information; the parenthetical scan inventory is the one place it leans toward marketing copy.

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?

No output schema exists, and 'one merge decision out' signals the return shape without detailing its structure — a minor gap for a gatekeeper whose verdict format matters. Everything else an agent needs (cost, payment prerequisite, atomic billing, size ceiling via the schema) is present.

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%, anchored by the schema's own description of 'diff' and 'context'. The description only reinforces that the input is a single unified diff; it adds nothing about 'context' or the undescribed 'packageJsonDiff' parameter, which is the one field an agent would most likely guess wrong about.

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?

States a specific verb and resource chain: takes a unified diff and returns a merge decision, enumerating the constituent checks (bug hunter, patch synthesizer, secret/dependency/SAST scans, Unicode/Trojan Source gate). It explicitly names the two composite members, diff_gatekeeper and unicode_safety_gate, so an agent can tell it apart from those siblings without opening any 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?

The bundling rationale ('runs diff_gatekeeper + unicode-safety-gate in one paid call for 20% less') gives a clear implied selection rule: use this when you want both gates. It stops short of an explicit inverse rule such as 'use diff_gatekeeper alone if you only need exploit scanning,' so the exclusion side is left to inference.

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