Review duplicate invoice candidates

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

Annotations declare readOnlyHint=false and idempotentHint=false, so the agent already knows this is not a pure read and is not safely repeatable. The description adds useful context the annotations do not (evidence is 'free', candidates require review, no payment approval), but it never explains the write implied by readOnlyHint=false — namely that save=true persists results — leaving the key behavioral question unanswered.

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 sentences, front-loaded with the core action and no filler; 'All evidence is free' and the review caveat are terse and each carries information. The first sentence is dense but not padded, so only marginal tightening is possible.

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?

With no output schema and no parameter descriptions, the description should at least sketch the return shape and the effect of 'save'; it gestures at output ('candidates require review') but never describes what a candidate group contains or that save=true persists it. Adequate to call the tool, incomplete for predicting the result.

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 description coverage is 0%, so the description must carry the load; it partially does by naming the grouping keys (entity, supplier, type, currency, reference, amount, date), which map onto the nested record fields. However, the 'save' parameter is never mentioned, and the description does not add format or constraint detail beyond what the schema itself encodes.

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 concrete action (group supplied records) and enumerates the matching rules (exact/normalized reference, exact amount/date within exact entity, supplier, type and currency), which lets an agent distinguish it from the report_*/license_* siblings. It never quite says 'detect duplicates' in prose, but the title plus the explicit match keys make the purpose unmistakable.

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 is implied rather than stated: 'Candidates require review; no payment approval' tells the agent the output is advisory and not an approval mechanism, which bounds how the result should be used. There is no explicit when-to-use/when-not or any named alternative, though the sibling set (reports, licensing) contains no plausible substitute for this tool.

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