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

Annotations only give generic hints (readOnly=false, idempotent=false, destructive=false). The description adds real behavioral context: it discloses the exact reversing entry (K likvidkonto / D 1510), that the invoice becomes unpaid again, and that the code posts automatically ('KODEN postar').

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 core sentence is well front-loaded and information-dense, but the trailing 'Argument: orgnr, invoice_id' fragment is a pure restatement of the schema and the 'Scope book' fragment is left unexplained.

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 two-param mutation tool with annotations and no output schema, the description covers the mechanism, the accounting result, and the scope. It omits failure conditions (e.g. behaviour when no payment exists) and permission requirements, but covers the essentials.

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 50% – invoice_id has no description anywhere – and the description does nothing to compensate, merely restating 'Argument: orgnr, invoice_id' without adding format, lookup, or constraint details beyond what the schema already says for orgnr.

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?

States a specific verb+resource ('Backa den senaste registrerade inbetalningen på en kundfaktura') and distinguishes itself from the sibling reverse_supplier_payment by scoping to customer invoices. It also names the exact scope ('book') and the accounting effect.

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: 'den senaste registrerade inbetalningen' hints that this targets the most recent payment, but there is no explicit when/when-not, no mention of prerequisites, and no routing against near neighbours like credit_customer_invoice or cancel_customer_invoice.

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