BuchhaltungsButler MCP-Server

Overview Schema Source Related Servers Discussions Admin

Vorgang mit Zuordnungen holen

bb_assignments_get

Read-onlyIdempotent

Fetches a receipt or payment with all its matched counterparts in one call, answering which receipt belongs to a given debit or which payment is linked to a given invoice.

Instructions

Holt einen Beleg oder eine Zahlung samt allen zugeordneten Gegenstücken in einem Aufruf und beantwortet damit 'welcher Beleg gehört zu dieser Abbuchung' und 'welche Zahlung hängt an dieser Rechnung'. Genau eines der beiden Kennungsfelder setzen. Ersetzt das Paar bb_receipts_get und bb_receipts_list_transactions sowie das Paar bb_transactions_get und bb_transactions_list_receipts. Konnte die Zuordnungsliste nicht geholt werden, steht dort null und nicht das leere Array; 'keine Zuordnung' wird nur behauptet, wenn die API es gesagt hat. Die Belegdatei kommt nie mit, dafür bb_receipts_get. Höchstens 5 Aufrufe an die API.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`max_rows`	No	Höchstzahl der angezeigten Zuordnungszeilen, 1 bis 200, Vorgabe 50. Wirkt serverseitig und geht nicht an die API; assignment_count nennt weiterhin alle gefundenen Zuordnungen.
`confirmed_only`	No	Wenn true, liefert die API nur bestätigte Zuordnungen, also solche, hinter denen eine bestätigte Buchung steht. Ohne Angabe kommen alle. Der Bestätigungsstand selbst steht in keiner Antwortzeile; dieses Werkzeug weist ihn deshalb nicht aus.
`response_format`	No	'concise' liefert nur die Felder, die einen Datensatz erkennbar machen und den nächsten Schritt erlauben. 'detailed' liefert den Datensatz so, wie die BuchhaltungsButler-API ihn ausgibt. Mit 'concise' beginnen und nur für die wenigen Datensätze auf 'detailed' wechseln, die wirklich geprüft werden müssen. Dieses Feld ist serverseitig und geht nicht an die API.	concise
`receipt_id_by_customer`	No	Die mandantenbezogene Belegnummer, zu finden über bb_records_collect oder bb_receipts_search. Genau eines der beiden Kennungsfelder ist zu setzen. In Suchergebnissen erscheint die Nummer als Zeichenkette; hier ohne Anführungszeichen übergeben. Beleg 1590 und Zahlung 1590 sind verschiedene Vorgänge.
`transaction_id_by_customer`	No	Die mandantenbezogene Nummer einer Zahlung, zu finden über bb_records_collect oder bb_transactions_search. Genau eines der beiden Kennungsfelder ist zu setzen. Der Nummernraum ist von dem der Belege getrennt.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`kind`	Yes
`bundle`	Yes
`record`	No
`success`	Yes
`enriched`	No
`assignments`	Yes
`not_enriched`	No
`confirmed_only`	No
`id_by_customer`	No
`assignment_count`	No
`assignments_status`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 13, 2026

TDQS

A4.6/5.0

Behavior4/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description nevertheless discloses valuable behavior: null vs empty-array semantics for failed assignment lists, the guard that 'keine Zuordnung' is only claimed when the API said so, and the API-call budget ('Höchstens 5 Aufrufe'). It doesn't discuss pagination of the assignment rows, but the max_rows note partially covers that.

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?

Front-loaded with the core purpose and the question it answers, followed by invocation rules and behavioral caveats in logical order. It is dense and every sentence carries information, though the 'Ersetzt das Paar...' sentence is somewhat list-like and could be tightened.

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 an output schema exists, the description needn't explain return fields, and it doesn't. It covers what the schema and annotations can't: sibling replacement, exactly-one-of, null-vs-empty semantics, file exclusion, and the API call limit. Nothing an agent needs to call this correctly is missing.

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 description coverage is 100%, so baseline is 3. The description adds meaning beyond the schema: it states the exactly-one-of constraint on the two ID fields, clarifies that string-form IDs from search results must be passed unquoted, and warns that receipt 1590 and transaction 1590 are distinct entities. That is genuine added value over the schema's per-parameter text.

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?

Specific verb+resource: 'Holt einen Beleg oder eine Zahlung samt allen zugeordneten Gegenstücken'. It even states the user questions it answers ('welcher Beleg gehört zu dieser Abbuchung'). It explicitly distinguishes itself from the four siblings it replaces (bb_receipts_get/list_transactions and bb_transactions_get/list_receipts), making its scope 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?

Explicit guidance: 'Genau eines der beiden Kennungsfelder setzen' tells the invocation rule, and 'Ersetzt das Paar X und Y' tells the agent when to prefer it over the sibling pairs. It also names a when-not case ('Die Belegdatei kommt nie mit, dafür bb_receipts_get'), routing the file-retrieval use case elsewhere.

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

Deploy Server