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

Annotations only declare the generic safety profile (not read-only, not destructive, not idempotent, closed-world). The description adds genuinely non-obvious behavior: duplicate proof references are rejected on the second submission, payments without an assessment are flagged no_evidence, a router key is required except for pr_sample, dry_run writes nothing, and the tool never moves money. That is exactly the mutation-specific context the annotations cannot carry.

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 critical facts (reconcile released payments, dry_run is safe, never sends money) are front-loaded, and the field enumeration is dense but informative. The first sentence is long and list-heavy, which slows scanning, but no sentence is 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?

For a four-parameter mutation tool with no output schema, the description covers what is written, the validate-only path, the duplicate-proof-ref failure mode, the no_evidence flag, and the auth requirement. What it omits are the shape or confirmation of the result (e.g. per-payment status returned) and any partial-failure behavior when reconciling a batch of payments.

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%, so the baseline is 3, but the description still adds meaning: it explains the access_key requirement and its pr_sample exception (a constraint not in the schema text) and states that reusing the same proof_ref is rejected, which clarifies the semantics of that array field. The dry_run explanation largely restates the schema description, which caps it below 5.

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 a concrete verb and resource: 'Reconciles each released payment in a run with what landed', and then enumerates exactly which fields are captured (amount sent, landed amount, settlement time, proof reference, rate receipt, realised cost, range position). This is far more specific than the name alone. It stops short of naming the siblings it competes with (record_landed, reconcile_outcome, swapeazi_guardrail_reconcile), so an agent cannot fully disambiguate from purpose text alone.

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: it applies to 'each released payment in a run', and dry_run is described as a validate-only mode. There is no explicit 'use this instead of record_landed / reconcile_outcome when...' guidance, and no stated preconditions such as the run needing to be released first. The when-to-use signal exists but must be inferred.

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