BuchhaltungsButler MCP-Server

Overview Schema Source Related Servers Discussions Admin

Rechnungsentwurf erzeugen

bb_invoices_create_draft

Create a draft invoice in BuchhaltungsButler without a final number or PDF. Use it for internal coordination, like an offer awaiting approval, before the final invoice is generated.

Instructions

Erzeugt in BuchhaltungsButler einen Rechnungsentwurf: ohne endgültige Nummer, ohne PDF, aber als sichtbares Objekt in der Rechnungsstellung des Mandanten. Zu nehmen, solange der Vorgang noch abgestimmt wird, etwa ein Angebot zur internen Durchsicht; bb_invoices_create erzeugt die endgültige, nummerierte Rechnung, bb_invoices_create_einvoice die E-Rechnung. Die Antwort trägt ausschließlich success und message: keine id_by_customer, keine invoicenumber, und die API kennt keinen Pfad, den Entwurf später zu lesen. Die Felder invoicenumber, due_days und payment_reference führt dieser Endpunkt nicht. Schreibt in die echten Buchhaltungsdaten von BuchhaltungsButler. Die API bietet keinen Endpunkt, das rückgängig zu machen.

Input Schema

TableJSON Schema

Name	Required	Description
`zip`	No	Postleitzahl, zum Beispiel "28195".
`city`	No	Ort, zum Beispiel Bremen.
`date`	Yes	Rechnungsdatum als YYYY-MM-DD, zum Beispiel 2026-04-26. Ein leerer String wird abgelehnt; das Feld stattdessen weglassen. Ob der Wert im Entwurf erhalten bleibt, ist nicht verifiziert.
`email`	No	E-Mail-Adresse, zum Beispiel rechnung@beispiel.de.
`items`	Yes	Die Positionen des Entwurfs, je Eintrag eine Zeile des späteren Dokuments. item_amount ist die Menge und nicht der Betrag; der Preis einer Einheit steht in item_single_price. Die BuchhaltungsButler-API nimmt diese Werte als parallele Arrays entgegen (item_name, item_amount, item_unit, item_vat, item_single_price, item_description); dieses Werkzeug nimmt eine Positionsliste und rechnet sie um, wodurch die Arrays zwingend gleich lang sind.
`street`	No	Straße und Hausnummer, zum Beispiel Hauptstraße 12.
`country`	No	Land des Empfängers, deutscher Ländername oder ISO-Code, zum Beispiel DK.
`language`	No	Sprache der festen Beschriftungen: 'de_DE' oder 'en_US', ohne Angabe 'de_DE'. Positionstexte werden nicht übersetzt.
`company_name`	Yes	Firmenname des Empfängers, wie er auf dem Dokument erscheint.
`invoice_type`	Yes	Art des Dokuments: 'invoice' Rechnung, 'credit' Gutschrift, 'offer' Angebot. Heißt in der API type, hier umbenannt: type ist dort siebenfach belegt.
`discount_type`	No	Rabatt auf die gesamte Rechnung: 'percent' Prozent, 'EUR' Euro. Positionsrabatte kennt die API nicht; gemeinsam mit discount_value setzen.
`show_bankdata`	No	true zeigt die im Mandanten hinterlegte Bankverbindung auf dem Dokument. Die Bankdaten selbst stammen aus den Mandanteneinstellungen.
`correspondence`	No	Anschreiben an den Empfänger, erscheint vor den Positionen.
`date_of_supply`	No	Liefer- oder Leistungsdatum, freier Text oder YYYY-MM-DD. Nur im Format YYYY-MM-DD wird der Wert zusätzlich date_delivery des entstehenden Belegs. Ein Datum nach date verwirft BuchhaltungsButler wegen der DATEV-Regel stillschweigend.
`discount_value`	No	Höhe des Rabatts mit Dezimalpunkt, zum Beispiel 10 oder 49.50. Die Bedeutung entscheidet discount_type.
`customer_number`	No	Kunden- oder Lieferantennummer des Mandanten.
`final_provisions`	No	Schlusstext des Dokuments, erscheint nach den Positionen.
`show_contactdata`	No	true zeigt die im Mandanten hinterlegten Kontaktdaten auf dem Dokument.
`show_prices_type`	Yes	Preisdarstellung: 'net' Nettopreise, 'gross' Bruttopreise. Danach werden die Werte in item_single_price gelesen.
`payment_conditions`	No	Zahlungsbedingungen als Text auf dem Dokument. Ein Fälligkeitsdatum entsteht daraus nicht; das Feld due_days führt dieser Endpunkt nicht.
`recurring_interval`	No	Rhythmus eines Rechnungsplans: 'weekly', 'monthly', 'quarterly' oder 'yearly'. Es entsteht ein dauerhafter Plan, der selbsttätig weitere Rechnungen erzeugt und über die API weder lesbar noch zu beenden ist.
`contact_person_name`	No	Name der Ansprechperson, zum Beispiel Maria Schmidt.
`recurring_date_next`	No	Nächster Termin des Rechnungsplans als YYYY-MM-DD. Ein leerer String wird abgelehnt; das Feld stattdessen weglassen. Pflicht, sobald recurring_interval gesetzt ist.
`additional_addressline`	No	Zusätzliche Adresszeile, zum Beispiel Gebäude B.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`data`	No
`created`	No
`message`	No
`success`	Yes
`endpoint`	No
`reversal`	No
`_contract_warnings`	No
`fields_not_returned`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 13, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Goes well beyond the annotations: warns that the response carries only success and message (no id_by_customer, no invoicenumber) and that no API path exists to read the draft later. It also discloses that the endpoint excludes invoicenumber, due_days, and payment_reference, that it writes to real accounting data, and that there is no undo endpoint. This is unusually rich disclosure for a write operation.

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-loads what the tool creates and its distinguishing traits before moving to sibling routing and behavioral caveats. The sentences are dense but each carries a specific fact (missing fields, no read path, no undo). Slightly heavy at ~90 words, but no filler.

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 a 24-parameter write tool with an output schema, the description covers the critical behavioral gaps: what is omitted from the response, what the API cannot do afterward, and how it relates to sibling creation endpoints. The output schema handles return shape, so nothing essential is missing.

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

Parameters3/5

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

Schema description coverage is 100% and each field already has a detailed description, including field-name remapping (type → invoice_type), enum semantics, format rules, and DATEV warnings. The tool description itself adds no additional parameter-level information, so baseline 3 applies under high coverage.

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 names the verb and resource precisely ('Erzeugt in BuchhaltungsButler einen Rechnungsentwurf') and enumerates distinguishing characteristics: no final number, no PDF, but a visible object. It further separates itself from the sibling tools bb_invoices_create and bb_invoices_create_einvoice by name.

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?

States explicitly when to use it ('solange der Vorgang noch abgestimmt wird, etwa ein Angebot zur internen Durchsicht') and names both alternatives with their distinct roles. The routing between draft, final invoice, and e-invoice is unambiguous.

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

Deploy Server