Skip to main content
Glama
ninetails-io

gnucash-mcp

apply_credit_note

Net a posted credit note against a posted invoice or bill from the same owner, moving the credit balance between A/R or A/P lots without cash.

Instructions

Net a posted credit note against a posted invoice or bill from the same owner. No cash moves — the credit balance transfers between lots on the same A/R or A/P account.

This is the most common credit-note settlement path: the bookkeeper issues a credit note against an overcharge, then nets it against the next invoice from that customer (or applies it to an outstanding bill on the vendor side). Use pay_document instead when the credit note will be settled by sending or receiving cash.

Args: credit_note_id: The credit note to apply (must be posted). applies_to_invoice_id: The target invoice/bill (must be posted, same owner, same currency, same A/R or A/P post account). Need not be the document the credit note was created against — that link is provenance, and the response notes the divergence when this target differs from it. amount: Decimal-string amount to apply, in the document currency. Defaults to min(credit_note_ remaining, target_remaining) — apply as much as possible. apply_date: ISO date for the netting transaction. Defaults to today. owner_type: Optional 'customer' or 'vendor' disambiguator for ID collisions.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
amountNo
apply_dateNo
owner_typeNo
credit_note_idYes
applies_to_invoice_idYes

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.4.2

TDQS

A5/5.0
Behavior5/5

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

Beyond the annotations, the description discloses meaningful behavioral traits: the transaction is non-cash, it transfers credit balance between lots, both documents must be posted and share owner/currency/account, and the response notes divergence when the target differs from the provenance document. It also explains the amount default behavior and date default, which directly informs call behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core operation, then provides context, an explicit alternative, and well-organized parameter documentation. Every sentence contributes either behavioral context, usage guidance, or parameter semantics. The Args block is formatted clearly and maps directly to the input schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 5 parameters, no schema descriptions, and an output schema exists, this description covers everything an agent needs to call the tool correctly: operation semantics, constraints, defaults, ownership requirements, and when to choose an alternative. The only missing details would be error cases, but the detailed constraints and output schema sufficiently cover the core contract.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description carries the full burden, and it succeeds. Every parameter is explained with constraints, defaults, and format: credit_note_id must be posted, applies_to_invoice_id must be posted and share owner/currency/account, amount is a decimal string defaulting to max possible, apply_date is ISO defaulting to today, and owner_type disambiguates ID collisions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a precise verb and resource: 'Net a posted credit note against a posted invoice or bill from the same owner.' It immediately clarifies that no cash moves, and the mechanism (credit balance transfers between lots on the same A/R or A/P account) distinguishes it from payment-related siblings like pay_document.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when this tool is the right choice—'the most common credit-note settlement path'—and provides a direct exclusion: 'Use pay_document instead when the credit note will be settled by sending or receiving cash.' This gives an agent clear decision criteria without needing to inspect other tools.

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