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

With readOnlyHint and openWorldHint already declared, the description still adds real value: the data-quality taxonomy (LIVE/INDICATIVE/HISTORICAL/ESTIMATED), the warning that estimated savings are never realised, the shared free allowance, and the fact that an analysis is posted and can later be read back via pa_ id. The POST-and-keep behaviour sits in mild tension with readOnlyHint, but since it stores an analysis artifact rather than mutating payments it does not amount to a contradiction.

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?

Output contents are front-loaded in the opening sentence, which is the right priority for a tool with no output schema, and the ~90 words are defensible for 15 parameters. The semicolon-chained first sentence and the fragment-like later clauses ('One analysis (POST /api/v1/payment-analyses)', 'Free: shares the route-assessment allowance.') are terse to the point of being cryptic.

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?

Because there is no output schema, the description correctly spends its budget enumerating return values and flagging the estimate labels, and it discloses the quota model. For a 15-parameter tool it is nearly complete; the main gap is that it never explains which input path (invoice_text, explicit fields, or analysis_id) takes precedence, which an agent must infer from the schema alone.

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% across 15 parameters including nested objects, so the schema already carries the detailed semantics (weights keys, existing_provider shape, invoice_text alternative). The description adds only framing — that the comparison is against the current provider and that alternative routes are costed at the same size — without clarifying priority-vs-weights interaction, amount-vs-beneficiary_amount, or invoice_text-vs-explicit-fields precedence.

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 first sentence names the specific computation (effective rate, FX spread, three fee types, total in money and bps, beneficiary receipt) and adds that alternative routes are priced at the same size, so an agent knows exactly what it gets back. It does not distinguish itself from close siblings such as compare_payment_providers, price_routes or swapeazi_landed_cost; 'the same service for every payment-intelligence tool' gestures at a family but names no boundary.

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: 'through your current provider against the official rate' signals the scenario is benchmarking an existing provider quote, and the free-tier note signals a shared allowance. There is no explicit when-to-use versus the many route/pricing siblings, and no when-not-to-use or prerequisite (e.g. what must be supplied when analysis_id is omitted).

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