Buchhaltungsbutler MCP

Postings: add receipt posting

postings_create_for_receipt

Create accounting postings for existing receipts, splitting amounts across accounts, VAT rates, and cost centers. For receipts already in BuchhaltungsButler.

Instructions

🟡 WRITE · creates data: Creates new records (receipts, transactions, postings, invoices, master data). Not idempotent: calling twice may create duplicates.

add receipt posting

Add postings for a specified receipt. Important: Receipt postings are only available if creditor or debtor posting is activated!

IMPORTANT: If you add postings to a receipt with foreign currency, you have to get that receipt (/receipts/get/id_by_customer) and find the calculated amount before performing this request.

Use to book one or more receipts that already exist in BuchhaltungsButler, splitting each across posting accounts, VAT rates and cost centres.

For a journal entry with no receipt behind it, use postings_create_free.

Takes one or many: pass an array of receipts in receipts. A single record is an array of one.

The per-receipt arrays (postingaccounts, amounts, vats, postingtexts) are positional: index 0 of each describes the same split line, so they must all have the same length. Not idempotent. Reversible with postings_unconfirm_for_receipt while the posting is not fixed.

Endpoint: POST /postings/add-batch/receipts

Input Schema

TableJSON Schema

Name	Required	Description	Default
`receipts`	Yes	an array of receipt postings, each receipt posting has the same field declaration and validation as the postings/add/receipt endpoint

Output Schema

TableJSON Schema

Name	Required	Description
`errors`	No
`success`	Yes	Success boolean
`receipts`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv1.1.3Sep 26, 2026

removedInput schema / properties / receipts / items / properties / postingstexts

Removed value: -{
-  "items": {
-    "type": "string"
-  },
-  "type": "array"
-}

addedInput schema / properties / receipts / items / properties / postingtexts

Added value: +{
+  "description": "An array of posting texts.\n\nUsage:\n\"postingtexts\" : ['text of posting 1', 'text of posting 2']",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

changedInput schema / properties / receipts / items / required

Previous value: -[
-  "receipt_id_by_customer",
-  "postingaccounts",
-  "vats",
-  "amounts",
-  "creditor",
-  "debtor"
-]New value: +[
+  "receipt_id_by_customer",
+  "postingaccounts",
+  "vats",
+  "amounts",
+  "postingtexts"
+]

changedOutput schema / properties / errors / items / properties / request_data / type
```
Previous value: -"array"New value: +[
+  "array",
+  "object"
+]
```

Addedv1.1.2Sep 15, 2026

TDQS

A4.8/5.0

Behavior5/5

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

The description matches and extends annotations: it confirms this is a write operation, explicitly warns that calling twice may create duplicates (consistent with idempotentHint=false), and adds reversibility details via postings_unconfirm_for_receipt while the posting is not fixed. This goes well beyond the annotation fields.

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

Conciseness4/5

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

The description is well-structured with warnings, usage guidance, alternatives, and a clear endpoint. It is longer than average, and 'Not idempotent' is repeated, but the information density is high and each section serves a distinct purpose.

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?

For a write tool that books complex multi-line postings, the description covers the key operating constraints: activation prerequisite, foreign-currency handling, array positional semantics, duplicate risk, reversibility, and the free-posting alternative. The output schema exists, so return-value documentation is not required.

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

Parameters4/5

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

Schema coverage is already 100%, but the description adds crucial usage semantics: receipts can be a single-element array or multiple receipts, and the inner arrays are positional and must have the same length. These details are not obvious from the schema alone and help the agent construct valid input.

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 states a specific action ('Add postings for a specified receipt') and the resource ('receipts'), and clarifies the actual use case: booking one or more existing receipts split across posting accounts, VAT rates and cost centres. It also distinguishes itself from postings_create_free, making its purpose unambiguous.

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 explains when to use this tool vs postings_create_free, and gives prerequisites: receipt postings are only available if creditor or debtor posting is activated. It also warns about the foreign-currency prerequisite, so an agent knows what must be checked before calling.

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

Deploy Server