wave_delete_invoice_paymentDelete a recorded invoice payment to mark the invoice unpaid by that amount.
Delete a recorded invoice payment; the invoice becomes unpaid by that amount.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Invoice payment ID |
Changes observed during successful MCP inspections.
v1.0.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description contributes real added context beyond that: it states the downstream consequence that the invoice is reduced back to unpaid by that amount, which helps an agent predict side effects. It stops short of saying whether the deletion is reversible, whether the invoice's status/history is recalculated, or what happens to linked transaction records.
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?
A single front-loaded sentence states the action and then the effect, with no boilerplate or repetition. Every clause earns its place; nothing could be removed without losing information.
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 one-parameter destructive tool with full annotation coverage and no output schema, the definition supplies the action, the target, and the accounting consequence — enough for correct invocation. The remaining gap is procedural context (irreversibility, permissions, how to obtain a valid payment ID) that an agent might want before firing a destructive call.
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?
There is a single required parameter and schema description coverage is 100%, with the schema already labeling it "Invoice payment ID". The description adds no format, sourcing guidance (e.g., obtain via wave_get_invoice_payment or wave_list_payments), or validation notes, so the baseline 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 pairs the specific verb "delete" with the specific resource "recorded invoice payment" and adds the resulting state change. It is unambiguous, though it never explicitly contrasts with wave_delete_estimate_payment or wave_update_invoice_payment; the distinction is carried mainly by the tool name rather than the description.
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 only implied: the word "recorded" hints that this removes an existing payment rather than a pending one, but there is no statement of when to delete versus correcting via wave_update_invoice_payment, nor any prerequisite (e.g., payment must exist, be unapplied). An agent must infer the selection criteria from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.