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

Beyond the annotations, the description discloses the output shape ('expected band beside the realised cost, signed') and, importantly, an aggregation/privacy trait: the outcome is stored only by pair and size band, not by identifier. It also explains the feedback effect on future maps. What it omits is the consequence of idempotentHint=false — whether resubmitting the same outcome double-counts the band — which matters for a non-read-only, non-idempotent write.

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?

Four short sentences, front-loaded with the trigger condition and followed by return shape, persistence behaviour, and scope. The terse fragments 'Economics only. Free.' carry real information about scope and cost. Slight density of internal jargon ('the map it was chosen from', 'signed') costs a point.

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 5-parameter mutation with a nested object and no output schema, the description does well on return values and storage semantics. It is incomplete on the two things an agent most needs for a non-idempotent write: whether a repeat call creates a duplicate outcome record, and how to correct or supersede a mistaken submission.

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 100%, and the nested realised object is fully documented, including the sent/landed amounts versus all_in_bps_vs_ref alternative. The description echoes that alternative ('or the all-in cost') but adds no syntax, format, or validation detail beyond the schema, so the baseline of 3 applies.

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 action (post what was sent and what landed against the originating map) with a clear post-settlement scope ('after the money moved'). It is distinguishable from a generic settlement tracker by emphasising the expected-vs-realised comparison, but it never names the close siblings record_landed or reconcile_payment, so an agent cannot route between them from this 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?

'After the money moved' gives a timing cue, which is genuine usage guidance for when the tool becomes relevant. However, there is no explicit when-not, no statement of prerequisites (must a map exist first? must candidate_id_used have been selected earlier?), and no reference to alternatives among the many reconciliation-adjacent siblings.

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