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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses critical behavior: amount is in MAJOR units, it ADDS to existing paid balance rather than replacing it, omitting it settles the remainder, and overpayments are refused with the open balance named. This matches the non-idempotent annotation by warning that each call likely adds another payment record. It could add what the response contains or whether the action is reversible, but it is already strong.

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?

Three short sentences, no fluff, and the most critical constraint (MAJOR units + additive behavior) is front-loaded. Every sentence carries behavioral or usage value. It is efficiently scannable for an agent.

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?

Given there is no output schema, the description covers the main invocation-relevant behaviors: amount semantics, default settlement, and error case. The only mildly missing piece is what a successful call returns (e.g., updated invoice, payment record) and whether multiple partial payments are intended to accumulate. These are minor since the core call semantics are fully stated.

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 80%, so the schema already documents amount, method, paid_date, and reference. The description repeats the amount semantics in clearer emphasis (MAJOR units, ADDS, omit to settle) but does not explain the 'number' parameter, which has no schema description. This is adequate but not additive enough to rise above baseline.

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?

Description opens with 'Record a payment on one invoice,' a specific verb and resource that clearly differentiates this from invoice_create, invoice_list, and invoice_pdf. The additive payment semantics further pin down the exact operation. No other sibling tool performs payment recording.

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 description gives clear context: when a payment needs to be recorded against a single invoice, this is the tool. It does not explicitly name alternatives or exclusion conditions, but the use case is unambiguous given the sibling tool names. A dedicated when-not-to-use note would improve it to a 5.

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