Skip to main content
Glama

Brief versenden

order_send
Destructive

Versendet einen Brief per Post: prüft die Pflichtangaben des Absenders, die Empfängeradresse, den AVV und die Limits, erstellt die PDF und berechnet den Preis. Der Brief kommt über letterId (ein Entwurf) oder inline: dann ist der Text content (Fließtext) oder blocks (strukturiert: Tabellen, Überschriften, Summenzeilen), genau eines von beiden. Kompaktes blocks-Beispiel: {"blocks":[{"type":"heading","text":"Rechnung"},{"type":"table","columns":[{"key":"text","label":"Artikel","width":"grow"},{"key":"sum","label":"Summe","align":"right","format":"eur"}],"rows":[{"text":"Beratung","sum":32000}]},{"type":"totals","lines":[{"label":"Gesamt","amountCents":32000,"emphasis":true}]}]} Schema-Referenz: frankki://blocks-guide. dryRun: true ist eine kostenfreie Probe: sie liefert Preis, Seite 1 als Bild und die Liste checks (jede Prüfung mit passed, failed oder skipped), und der Brief bleibt unversandt; ein zweiter Aufruf mit denselben Werten und dryRun: false versendet genau diesen Brief. Ein echter Versand wartet auf Freigabe. Autopilot ist eine Dashboard-Einstellung, die die Person selbst steuert: mit ihm geht ein Standardbrief aus eigener freigegebener Vorlage (templateId plus templateVersionId) an einen Empfänger aus dem Adressbuch nach 10 Minuten raus. saveRecipient: true trägt den Empfänger dabei ein, humanSummary nennt die Uhrzeit, order_status und order_cancel nehmen die approvalId. mcp_health meldet unter setup, welcher Freigabeweg gilt. Für eine Mahnung, Kündigung, Mieterhöhung oder einen anderen Brief mit Frist gibt es das Einschreiben mit Nachweis; seinen Preis liefert shipping_quote. Eine fertige eigene PDF geht unverändert raus: letter_upload_pdf prüft und speichert sie, order_send versendet sie dann mit pdfStorageKey und Empfänger. EN: Sends a letter by post: checks the sender's mandatory details, the recipient address, the AVV and the limits, creates the PDF and calculates the price. The letter arrives via letterId (a draft) or inline: then the body is content (plain text) or blocks (structured: tables, headings, totals lines), exactly one of the two. Compact blocks example: {"blocks":[{"type":"heading","text":"Rechnung"},{"type":"table","columns":[{"key":"text","label":"Artikel","width":"grow"},{"key":"sum","label":"Summe","align":"right","format":"eur"}],"rows":[{"text":"Beratung","sum":32000}]},{"type":"totals","lines":[{"label":"Gesamt","amountCents":32000,"emphasis":true}]}]} Schema reference: frankki://blocks-guide. dryRun: true is a free rehearsal: it returns the price, page 1 as an image and the checks list (each gate with passed, failed or skipped), and the letter stays unsent; a second call with the same values and dryRun: false sends exactly that letter. A real send waits for approval. Autopilot is a dashboard setting the person controls: with it, a standard letter from an own released template (templateId plus templateVersionId) to an address-book recipient leaves after 10 minutes. saveRecipient: true adds the recipient on the way, humanSummary names the time, order_status and order_cancel take the approvalId. mcp_health reports under setup which approval path applies. For a Mahnung, Kündigung, Mieterhöhung or other deadline letter, Einschreiben adds a proof of posting; shipping_quote returns its price. A finished own PDF goes out unchanged: letter_upload_pdf checks and stores it, then order_send sends it with pdfStorageKey and the recipient.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "order_send"
  }
}

Input Schema

NameRequiredDescriptionDefault
colorNoOhne Angabe wird die Farbe automatisch erkannt. EN: If omitted, colour is detected automatically.
blocksNoStrukturierter Briefinhalt als typisierte Blöcke, an Stelle von content. Limits: 200 Blöcke, 100 Zeilen/Tabelle, 20 Spalten, 2000 Zeichen/Zelle, 10 Bilder, 262144 Bytes. Jeder Block braucht type; erlaubte Typen: paragraph, heading, keyValue, checkboxRow, fillLine, table, totals, columns, box, image, spacer, pageBreak. Feldreferenz: MCP-Ressource frankki://blocks-guide. EN: Structured letter content as typed blocks, in place of content. Limits: 200 blocks, 100 rows per table, 20 columns, 2000 characters per cell, 10 images, 262144 bytes. Every block needs type; allowed types: paragraph, heading, keyValue, checkboxRow, fillLine, table, totals, columns, box, image, spacer, pageBreak. Field reference: MCP resource frankki://blocks-guide.
designNoExakter Briefdesign-Snapshot aus template_apply_with_merge_fields.composition.design. Hat Vorrang vor designId und verhindert, dass eine spätere Designänderung die freigegebene Vorlagenkomposition verändert. EN: Exact letter-design snapshot from template_apply_with_merge_fields.composition.design. Takes precedence over designId and prevents later design edits from changing the released template composition.
dryRunNoProbe ohne Kosten; liefert Seite 1 als Bild und die Liste checks (jede Prüfung mit passed, failed oder skipped). EN: Free rehearsal; returns page 1 as an image and the checks list (each gate with passed, failed or skipped).
contentNoBrieftext als Fließtext. Genau eines von content und blocks. EN: Letter body as plain text. Exactly one of content and blocks.
expressNo
subjectNo
auditTagNo
designIdNoGespeichertes Briefdesign für diesen Versand. Ohne Angabe gilt in dieser Reihenfolge: das am Entwurf gespeicherte Design (beim Versand über letterId), sonst das Standard-Design des Absenderprofils, sonst keins. EN: Saved letter design for this send. If omitted, in order: the design stored on the draft (when sending by letterId), else the sender profile default design, else none.
letterIdNoBestehender Entwurf. Alternativ kommt der Brief inline. EN: Existing draft. The letter can come inline instead.
reasoningNo
referenceNoWerte für diesen Brief (Vorgangsnummer, Ihr Zeichen, Kundennummer, QR-Parameter ...). Sie füllen den Infoblock und den Barcode. EN: Per-letter values (Vorgangsnummer, Ihr Zeichen, customer number, QR parameters ...). They fill the info block and the barcode.
styleDefsNoBenannte Stile für das ganze Dokument (max. 24). Blöcke referenzieren sie über style. Stilfelder: frankki://blocks-guide. EN: Named document styles (max 24); blocks reference them via style. Style fields: frankki://blocks-guide.
presetNameNo
templateIdNo
scheduledAtNo
signatureIdNo
approvalModeNoWie der Versand freigegeben wird. 'draft' und 'review' stellen ihn in die Freigabe-Warteschlange, statt sofort zu versenden. 'auto' wird derzeit genauso behandelt wie 'review': der Brief wartet auf die Freigabe durch einen Menschen. Mit einem Test-Token läuft jeder Modus als Probe. Auch diese beiden reservieren den Betrag beim Einreichen im Wallet, damit ein freigegebener Brief später nicht am Guthaben scheitert. Ohne Deckung kommt INSUFFICIENT_FUNDS zurück und es wird nichts angelegt. Einen Entwurf ohne Wallet-Deckung legt letter_create_draft an. EN: How the send is approved. 'draft' and 'review' put it into the approval queue instead of sending immediately. 'auto' is currently treated exactly like 'review': the letter waits for a person to approve it. With a test token every mode runs as a rehearsal. Both still reserve the amount in the wallet at submit time, so an approved letter cannot fail on funds later. Without cover the call returns INSUFFICIENT_FUNDS and nothing is created. letter_create_draft creates a draft with no wallet cover.
deliveryTypeNoStandard standard. EN: Defaults to standard.
letterheadIdNoBestimmter Briefkopf für diesen Versand. Ohne Angabe wird der Standard-Briefkopf verwendet. EN: A specific letterhead for this send. If omitted, the default letterhead is used.
maxCostEurosNoMaximalbetrag in Euro. Liegt der Preis darüber, wird abgebrochen. EN: Maximum amount in euros. If the price is above it, the call is aborted.
priceVersionNoOptional: die priceVersion aus einem vorherigen shipping_quote. Weicht der Preis beim Versand davon ab, wird mit PRICE_CHANGED abgebrochen, bevor etwas berechnet wird. EN: Optional: the priceVersion from an earlier shipping_quote. If the price at send time differs, the call is aborted with PRICE_CHANGED before anything is charged.
recipientZipNo
clientOrderIdNoIdempotenzschlüssel: eine beliebige Zeichenkette (1-200 Zeichen, z. B. 'mahnung-kunde42-2026-07-20'; kein UUID-Format nötig). Ein erneuter Aufruf mit demselben Wert liefert dieselbe Bestellung, statt ein zweites Mal zu versenden. Der Namensraum 'approval:' ist reserviert. EN: Idempotency key: any string (1-200 characters, e.g. 'mahnung-kunde42-2026-07-20'; no UUID format required). A repeat call with the same value returns the same order instead of sending a second time. The 'approval:' namespace is reserved.
pdfStorageKeyNoDer Schlüssel aus letter_upload_pdf, wenn eine eigene fertige PDF der Brief ist, an Stelle von Betreff und Text. Dazu gehören die Empfängerfelder, so wie sie auf der PDF stehen, und die deliveryType. Der Versand prüft, ob die Adresse im Adressfeld der Versandart steht, beim Standardbrief 60 bis 85,5 mm von oben, beim Einschreiben 68 bis 85,5 mm. Steht sie woanders, nennt PDF_LAYOUT_INVALID die Millimeter zum Verschieben. EN: The key from letter_upload_pdf, when an own finished PDF is the letter, in place of subject and body. It goes with the recipient fields exactly as printed on the PDF, and the deliveryType. The send checks that the address sits in the address zone of the delivery method, 60 to 85.5 mm from the top for a standard letter and 68 to 85.5 mm for Einschreiben. If it sits elsewhere, PDF_LAYOUT_INVALID gives the millimetres to move.
recipientCityNo
recipientNameNo
saveRecipientNotrue übernimmt den Empfänger mit diesem Versand ins Adressbuch (für Autopilot). EN: true saves the recipient to the address book with this send (for autopilot).
coverTemplateIdNoAnschreiben für eine eigenständige Formularvorlage. EN: Cover letter for a standalone form template.
includeGeometryNoLiefert zusätzlich die Layoutdaten der Seiten. EN: Also returns the page layout data.
mandantennummerNo
recipientStreetNo
senderAddressIdNo
senderProfileIdNo
includeSignatureNo
recipientCompanyNo
recipientCountryNoISO-3166-alpha-2, Standard DE. EN: ISO 3166-1 alpha-2, defaults to DE.
letterheadEnabledNofalse lässt den Briefkopf für diesen einen Versand weg. EN: false leaves the letterhead off for this one send.
templateVersionIdNoExakte freigegebene Vorlagenversion. Nur gemeinsam mit templateId; der Server rendert sie mit templateMergeValues neu und ignoriert mitgesendeten Betreff/Inhalt. EN: Exact released template version. Only with templateId; the server rerenders it with templateMergeValues and ignores caller-supplied subject/content.
recipientAddressIdNoEine gespeicherte Adresse aus dem Adressbuch (address_list) als Empfänger, an Stelle der Felder recipientName bis recipientCountry. EN: A saved address from the address book (address_list) as the recipient, in place of the fields recipientName to recipientCountry.
templateMergeValuesNoMerge-Werte für die exakte Vorlagenversion. EN: Merge values for the exact template version.
quotedUnitPriceCentsNoOptional: der Stückpreis in Cent aus einem vorherigen shipping_quote (unitPriceCents). Ist er gesetzt, entscheidet er den PRICE_CHANGED-Abgleich und liefert den alten Preis im Fehler mit. EN: Optional: the unit price in cents from an earlier shipping_quote (unitPriceCents). If set, it decides the PRICE_CHANGED comparison and returns the old price in the error.
recipientHouseNumberNo
coverTemplateVersionIdNoExakte freigegebene Version des Anschreibens. EN: Exact released version of the cover letter.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / recipientAddressId
      Added value: +{
      +  "description": "Eine gespeicherte Adresse aus dem Adressbuch (address_list) als Empfänger, an Stelle der Felder recipientName bis recipientCountry. EN: A saved address from the address book (address_list) as the recipient, in place of the fields recipientName to recipientCountry.",
      +  "format": "uuid",
      +  "type": "string"
      +}
  2. Changed11 schema fields changed
    • changedInput schema / properties / approvalMode / description
      Previous value: -"Wie der Versand freigegeben wird. 'draft' und 'review' stellen ihn in die Freigabe-Warteschlange, statt sofort zu versenden. 'auto' wird derzeit genauso behandelt wie 'review': der Brief wartet auf die Freigabe durch einen Menschen. Mit einem Test-Token läuft jeder Modus als Probe. Wichtig: auch diese beiden reservieren den Betrag beim Einreichen im Wallet, damit ein freigegebener Brief später nicht am Guthaben scheitert. Ohne Deckung kommt INSUFFICIENT_FUNDS zurück und es wird nichts angelegt. Willst du nur einen Entwurf ohne Wallet-Deckung, nutze letter_create_draft. EN: How the send is approved. 'draft' and 'review' put it into the approval queue instead of sending immediately. 'auto' is currently treated exactly like 'review': the letter waits for a person to approve it. With a test token every mode runs as a rehearsal. Note: both still reserve the amount in the wallet at submit time, so an approved letter cannot fail on funds later. Without cover the call returns INSUFFICIENT_FUNDS and nothing is created. For a plain draft with no wallet cover, use letter_create_draft."New value: +"Wie der Versand freigegeben wird. 'draft' und 'review' stellen ihn in die Freigabe-Warteschlange, statt sofort zu versenden. 'auto' wird derzeit genauso behandelt wie 'review': der Brief wartet auf die Freigabe durch einen Menschen. Mit einem Test-Token läuft jeder Modus als Probe. Auch diese beiden reservieren den Betrag beim Einreichen im Wallet, damit ein freigegebener Brief später nicht am Guthaben scheitert. Ohne Deckung kommt INSUFFICIENT_FUNDS zurück und es wird nichts angelegt. Einen Entwurf ohne Wallet-Deckung legt letter_create_draft an. EN: How the send is approved. 'draft' and 'review' put it into the approval queue instead of sending immediately. 'auto' is currently treated exactly like 'review': the letter waits for a person to approve it. With a test token every mode runs as a rehearsal. Both still reserve the amount in the wallet at submit time, so an approved letter cannot fail on funds later. Without cover the call returns INSUFFICIENT_FUNDS and nothing is created. letter_create_draft creates a draft with no wallet cover."
    • changedInput schema / properties / blocks / description
      Previous value: -"Strukturierter Briefinhalt als typisierte Blöcke (Alternative zu content, nie beides). Limits: 200 Blöcke, 100 Zeilen/Tabelle, 20 Spalten, 2000 Zeichen/Zelle, 10 Bilder, 262144 Bytes. EN: structured letter content as typed blocks (alternative to content, never both). Jeder Block braucht type; erlaubte Typen: paragraph, heading, keyValue, checkboxRow, fillLine, table, totals, columns, box, image, spacer, pageBreak. Die vollstaendige Feldreferenz liegt in der MCP-Ressource frankki://blocks-guide. EN: every block needs type; read frankki://blocks-guide for the complete field reference."New value: +"Strukturierter Briefinhalt als typisierte Blöcke, an Stelle von content. Limits: 200 Blöcke, 100 Zeilen/Tabelle, 20 Spalten, 2000 Zeichen/Zelle, 10 Bilder, 262144 Bytes. Jeder Block braucht type; erlaubte Typen: paragraph, heading, keyValue, checkboxRow, fillLine, table, totals, columns, box, image, spacer, pageBreak. Feldreferenz: MCP-Ressource frankki://blocks-guide. EN: Structured letter content as typed blocks, in place of content. Limits: 200 blocks, 100 rows per table, 20 columns, 2000 characters per cell, 10 images, 262144 bytes. Every block needs type; allowed types: paragraph, heading, keyValue, checkboxRow, fillLine, table, totals, columns, box, image, spacer, pageBreak. Field reference: MCP resource frankki://blocks-guide."
    • changedInput schema / properties / content / description
      Previous value: -"Brieftext als Fließtext. Entweder content ODER blocks, nie beides. EN: letter body as plain text. Either content OR blocks, never both."New value: +"Brieftext als Fließtext. Genau eines von content und blocks. EN: Letter body as plain text. Exactly one of content and blocks."
    • changedInput schema / properties / designId / description
      Previous value: -"Ein gespeichertes Briefdesign für diesen Versand verwenden. Ohne Angabe gilt in dieser Reihenfolge: das am Entwurf gespeicherte Design (beim Versand über letterId), sonst das Standard-Design des Absenderprofils, sonst keins. EN: Use a saved letter design for this send. If omitted, in order: the design stored on the draft (when sending by letterId), else the sender profile default design, else none."New value: +"Gespeichertes Briefdesign für diesen Versand. Ohne Angabe gilt in dieser Reihenfolge: das am Entwurf gespeicherte Design (beim Versand über letterId), sonst das Standard-Design des Absenderprofils, sonst keins. EN: Saved letter design for this send. If omitted, in order: the design stored on the draft (when sending by letterId), else the sender profile default design, else none."
    • changedInput schema / properties / dryRun / description
      Previous value: -"Probe ohne Kosten; liefert Seite 1 als Bild. EN: Free rehearsal; returns page 1 as an image."New value: +"Probe ohne Kosten; liefert Seite 1 als Bild und die Liste checks (jede Prüfung mit passed, failed oder skipped). EN: Free rehearsal; returns page 1 as an image and the checks list (each gate with passed, failed or skipped)."
    • changedInput schema / properties / letterId / description
      Previous value: -"Bestehender Entwurf. Alternativ den Brief inline angeben. EN: Existing draft. Alternatively provide the letter inline."New value: +"Bestehender Entwurf. Alternativ kommt der Brief inline. EN: Existing draft. The letter can come inline instead."
    • changedInput schema / properties / letterheadEnabled / description
      Previous value: -"Auf false setzen, um den Briefkopf für diesen einen Versand zu unterdrücken. EN: Set to false to suppress the letterhead for this one send."New value: +"false lässt den Briefkopf für diesen einen Versand weg. EN: false leaves the letterhead off for this one send."
    • changedInput schema / properties / pdfStorageKey / description
      Previous value: -"Der Schlüssel aus letter_upload_pdf, wenn eine eigene fertige PDF der Brief ist, statt Betreff und Text. Gib dazu die Empfängerfelder so an, wie sie auf der PDF stehen, und die deliveryType. Der Versand prüft, ob die Adresse im Adressfeld der Versandart steht, beim Standardbrief 60 bis 85,5 mm von oben, beim Einschreiben 68 bis 85,5 mm. Steht sie woanders, nennt PDF_LAYOUT_INVALID die Millimeter zum Verschieben. EN: The key from letter_upload_pdf, when your own finished PDF is the letter, in place of subject and body. Add the recipient fields exactly as printed on the PDF, and the deliveryType. The send checks that the address sits in the address zone of the delivery method, 60 to 85.5 mm from the top for a standard letter and 68 to 85.5 mm for Einschreiben. If it sits elsewhere, PDF_LAYOUT_INVALID gives the millimetres to move."New value: +"Der Schlüssel aus letter_upload_pdf, wenn eine eigene fertige PDF der Brief ist, an Stelle von Betreff und Text. Dazu gehören die Empfängerfelder, so wie sie auf der PDF stehen, und die deliveryType. Der Versand prüft, ob die Adresse im Adressfeld der Versandart steht, beim Standardbrief 60 bis 85,5 mm von oben, beim Einschreiben 68 bis 85,5 mm. Steht sie woanders, nennt PDF_LAYOUT_INVALID die Millimeter zum Verschieben. EN: The key from letter_upload_pdf, when an own finished PDF is the letter, in place of subject and body. It goes with the recipient fields exactly as printed on the PDF, and the deliveryType. The send checks that the address sits in the address zone of the delivery method, 60 to 85.5 mm from the top for a standard letter and 68 to 85.5 mm for Einschreiben. If it sits elsewhere, PDF_LAYOUT_INVALID gives the millimetres to move."
    • changedInput schema / properties / reference / description
      Previous value: -"Werte für diesen Brief (Vorgangsnummer, Ihr Zeichen, Kundennummer, QR-Parameter ...). Sie füllen den Infoblock und den Barcode. EN: Per-letter values (Vorgangsnummer, your reference, customer number, QR parameters ...). They fill the info block and the barcode."New value: +"Werte für diesen Brief (Vorgangsnummer, Ihr Zeichen, Kundennummer, QR-Parameter ...). Sie füllen den Infoblock und den Barcode. EN: Per-letter values (Vorgangsnummer, Ihr Zeichen, customer number, QR parameters ...). They fill the info block and the barcode."
    • changedInput schema / properties / saveRecipient / description
      Previous value: -"Empfänger mit diesem Versand ins Adressbuch übernehmen (für Autopilot). EN: Save the recipient to the address book with this send (for autopilot)."New value: +"true übernimmt den Empfänger mit diesem Versand ins Adressbuch (für Autopilot). EN: true saves the recipient to the address book with this send (for autopilot)."
    • changedInput schema / properties / styleDefs / description
      Previous value: -"Benannte Stile für das ganze Dokument (max. 24). Blöcke referenzieren sie über style. EN: named document styles (max 24); blocks reference them via style. Vollstaendige Stilfelder: frankki://blocks-guide. EN: complete style fields: frankki://blocks-guide."New value: +"Benannte Stile für das ganze Dokument (max. 24). Blöcke referenzieren sie über style. Stilfelder: frankki://blocks-guide. EN: Named document styles (max 24); blocks reference them via style. Style fields: frankki://blocks-guide."
  3. Changed1 schema field changed
    • addedInput schema / properties / pdfStorageKey
      Added value: +{
      +  "description": "Der Schlüssel aus letter_upload_pdf, wenn eine eigene fertige PDF der Brief ist, statt Betreff und Text. Gib dazu die Empfängerfelder so an, wie sie auf der PDF stehen, und die deliveryType. Der Versand prüft, ob die Adresse im Adressfeld der Versandart steht, beim Standardbrief 60 bis 85,5 mm von oben, beim Einschreiben 68 bis 85,5 mm. Steht sie woanders, nennt PDF_LAYOUT_INVALID die Millimeter zum Verschieben. EN: The key from letter_upload_pdf, when your own finished PDF is the letter, in place of subject and body. Add the recipient fields exactly as printed on the PDF, and the deliveryType. The send checks that the address sits in the address zone of the delivery method, 60 to 85.5 mm from the top for a standard letter and 68 to 85.5 mm for Einschreiben. If it sits elsewhere, PDF_LAYOUT_INVALID gives the millimetres to move.",
      +  "type": "string"
      +}
  4. Changed3 schema fields changed
    • addedInput schema / properties / dryRun / description
      Added value: +"Probe ohne Kosten; liefert Seite 1 als Bild. EN: Free rehearsal; returns page 1 as an image."
    • addedInput schema / properties / includeGeometry
      Added value: +{
      +  "description": "Liefert zusätzlich die Layoutdaten der Seiten. EN: Also returns the page layout data.",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / saveRecipient
      Added value: +{
      +  "description": "Empfänger mit diesem Versand ins Adressbuch übernehmen (für Autopilot). EN: Save the recipient to the address book with this send (for autopilot).",
      +  "type": "boolean"
      +}
  5. Changed13 schema fields changed
    • changedInput schema / properties / approvalMode / description
      Previous value: -"Wie der Versand freigegeben wird. 'draft' und 'review' stellen ihn in die Freigabe-Warteschlange, statt sofort zu versenden. Wichtig: auch diese beiden reservieren den Betrag beim Einreichen im Wallet, damit ein freigegebener Brief spaeter nicht am Guthaben scheitert. Ohne Deckung kommt INSUFFICIENT_FUNDS zurueck und es wird nichts angelegt. Willst du nur einen Entwurf ohne Wallet-Deckung, nutze letter_create_draft. EN: How the send is approved. 'draft' and 'review' put it into the approval queue instead of sending immediately. Note: both still reserve the amount in the wallet at submit time, so an approved letter cannot fail on funds later. Without cover the call returns INSUFFICIENT_FUNDS and nothing is created. For a plain draft with no wallet cover, use letter_create_draft."New value: +"Wie der Versand freigegeben wird. 'draft' und 'review' stellen ihn in die Freigabe-Warteschlange, statt sofort zu versenden. 'auto' wird derzeit genauso behandelt wie 'review': der Brief wartet auf die Freigabe durch einen Menschen. Mit einem Test-Token läuft jeder Modus als Probe. Wichtig: auch diese beiden reservieren den Betrag beim Einreichen im Wallet, damit ein freigegebener Brief später nicht am Guthaben scheitert. Ohne Deckung kommt INSUFFICIENT_FUNDS zurück und es wird nichts angelegt. Willst du nur einen Entwurf ohne Wallet-Deckung, nutze letter_create_draft. EN: How the send is approved. 'draft' and 'review' put it into the approval queue instead of sending immediately. 'auto' is currently treated exactly like 'review': the letter waits for a person to approve it. With a test token every mode runs as a rehearsal. Note: both still reserve the amount in the wallet at submit time, so an approved letter cannot fail on funds later. Without cover the call returns INSUFFICIENT_FUNDS and nothing is created. For a plain draft with no wallet cover, use letter_create_draft."
    • changedInput schema / properties / blocks / description
      Previous value: -"Strukturierter Briefinhalt als typisierte Bloecke (Alternative zu content, nie beides). Limits: 200 Bloecke, 100 Zeilen/Tabelle, 20 Spalten, 2000 Zeichen/Zelle, 10 Bilder, 262144 Bytes. EN: structured letter content as typed blocks (alternative to content, never both). Jeder Block braucht type; erlaubte Typen: paragraph, heading, keyValue, checkboxRow, fillLine, table, totals, columns, box, image, spacer, pageBreak. Die vollstaendige Feldreferenz liegt in der MCP-Ressource frankki://blocks-guide. EN: every block needs type; read frankki://blocks-guide for the complete field reference."New value: +"Strukturierter Briefinhalt als typisierte Blöcke (Alternative zu content, nie beides). Limits: 200 Blöcke, 100 Zeilen/Tabelle, 20 Spalten, 2000 Zeichen/Zelle, 10 Bilder, 262144 Bytes. EN: structured letter content as typed blocks (alternative to content, never both). Jeder Block braucht type; erlaubte Typen: paragraph, heading, keyValue, checkboxRow, fillLine, table, totals, columns, box, image, spacer, pageBreak. Die vollstaendige Feldreferenz liegt in der MCP-Ressource frankki://blocks-guide. EN: every block needs type; read frankki://blocks-guide for the complete field reference."
    • changedInput schema / properties / clientOrderId / description
      Previous value: -"Idempotenzschluessel: eine beliebige Zeichenkette (1-200 Zeichen, z. B. 'mahnung-kunde42-2026-07-20'; kein UUID-Format noetig). Ein erneuter Aufruf mit demselben Wert liefert dieselbe Bestellung, statt ein zweites Mal zu versenden. Der Namensraum 'approval:' ist reserviert. EN: Idempotency key: any string (1-200 characters, e.g. 'mahnung-kunde42-2026-07-20'; no UUID format required). A repeat call with the same value returns the same order instead of sending a second time. The 'approval:' namespace is reserved."New value: +"Idempotenzschlüssel: eine beliebige Zeichenkette (1-200 Zeichen, z. B. 'mahnung-kunde42-2026-07-20'; kein UUID-Format nötig). Ein erneuter Aufruf mit demselben Wert liefert dieselbe Bestellung, statt ein zweites Mal zu versenden. Der Namensraum 'approval:' ist reserviert. EN: Idempotency key: any string (1-200 characters, e.g. 'mahnung-kunde42-2026-07-20'; no UUID format required). A repeat call with the same value returns the same order instead of sending a second time. The 'approval:' namespace is reserved."
    • changedInput schema / properties / content / description
      Previous value: -"Brieftext als Fliesstext. Entweder content ODER blocks, nie beides. EN: letter body as plain text. Either content OR blocks, never both."New value: +"Brieftext als Fließtext. Entweder content ODER blocks, nie beides. EN: letter body as plain text. Either content OR blocks, never both."
    • changedInput schema / properties / design / description
      Previous value: -"Exakter Briefdesign-Snapshot aus template_apply_with_merge_fields.composition.design. Hat Vorrang vor designId und verhindert, dass eine spaetere Designaenderung die freigegebene Vorlagenkomposition veraendert. EN: Exact letter-design snapshot from template_apply_with_merge_fields.composition.design. Takes precedence over designId and prevents later design edits from changing the released template composition."New value: +"Exakter Briefdesign-Snapshot aus template_apply_with_merge_fields.composition.design. Hat Vorrang vor designId und verhindert, dass eine spätere Designänderung die freigegebene Vorlagenkomposition verändert. EN: Exact letter-design snapshot from template_apply_with_merge_fields.composition.design. Takes precedence over designId and prevents later design edits from changing the released template composition."
    • changedInput schema / properties / designId / description
      Previous value: -"Ein gespeichertes Briefdesign fuer diesen Versand verwenden. Ohne Angabe gilt in dieser Reihenfolge: das am Entwurf gespeicherte Design (beim Versand ueber letterId), sonst das Standard-Design des Absenderprofils, sonst keins. EN: Use a saved letter design for this send. If omitted, in order: the design stored on the draft (when sending by letterId), else the sender profile default design, else none."New value: +"Ein gespeichertes Briefdesign für diesen Versand verwenden. Ohne Angabe gilt in dieser Reihenfolge: das am Entwurf gespeicherte Design (beim Versand über letterId), sonst das Standard-Design des Absenderprofils, sonst keins. EN: Use a saved letter design for this send. If omitted, in order: the design stored on the draft (when sending by letterId), else the sender profile default design, else none."
    • changedInput schema / properties / letterheadEnabled / description
      Previous value: -"Auf false setzen, um den Briefkopf fuer diesen einen Versand zu unterdruecken. EN: Set to false to suppress the letterhead for this one send."New value: +"Auf false setzen, um den Briefkopf für diesen einen Versand zu unterdrücken. EN: Set to false to suppress the letterhead for this one send."
    • changedInput schema / properties / letterheadId / description
      Previous value: -"Bestimmter Briefkopf fuer diesen Versand. Ohne Angabe wird der Standard-Briefkopf verwendet. EN: A specific letterhead for this send. If omitted, the default letterhead is used."New value: +"Bestimmter Briefkopf für diesen Versand. Ohne Angabe wird der Standard-Briefkopf verwendet. EN: A specific letterhead for this send. If omitted, the default letterhead is used."
    • changedInput schema / properties / maxCostEuros / description
      Previous value: -"Maximalbetrag in Euro. Liegt der Preis darueber, wird abgebrochen. EN: Maximum amount in euros. If the price is above it, the call is aborted."New value: +"Maximalbetrag in Euro. Liegt der Preis darüber, wird abgebrochen. EN: Maximum amount in euros. If the price is above it, the call is aborted."
    • changedInput schema / properties / quotedUnitPriceCents / description
      Previous value: -"Optional: der Stueckpreis in Cent aus einem vorherigen shipping_quote (unitPriceCents). Ist er gesetzt, entscheidet er den PRICE_CHANGED-Abgleich und liefert den alten Preis im Fehler mit. EN: Optional: the unit price in cents from an earlier shipping_quote (unitPriceCents). If set, it decides the PRICE_CHANGED comparison and returns the old price in the error."New value: +"Optional: der Stückpreis in Cent aus einem vorherigen shipping_quote (unitPriceCents). Ist er gesetzt, entscheidet er den PRICE_CHANGED-Abgleich und liefert den alten Preis im Fehler mit. EN: Optional: the unit price in cents from an earlier shipping_quote (unitPriceCents). If set, it decides the PRICE_CHANGED comparison and returns the old price in the error."
    • changedInput schema / properties / reference / description
      Previous value: -"Werte fuer diesen Brief (Vorgangsnummer, Ihr Zeichen, Kundennummer, QR-Parameter ...). Sie fuellen den Infoblock und den Barcode. EN: Per-letter values (Vorgangsnummer, your reference, customer number, QR parameters ...). They fill the info block and the barcode."New value: +"Werte für diesen Brief (Vorgangsnummer, Ihr Zeichen, Kundennummer, QR-Parameter ...). Sie füllen den Infoblock und den Barcode. EN: Per-letter values (Vorgangsnummer, your reference, customer number, QR parameters ...). They fill the info block and the barcode."
    • changedInput schema / properties / styleDefs / description
      Previous value: -"Benannte Stile fuer das ganze Dokument (max. 24). Bloecke referenzieren sie ueber style. EN: named document styles (max 24); blocks reference them via style. Vollstaendige Stilfelder: frankki://blocks-guide. EN: complete style fields: frankki://blocks-guide."New value: +"Benannte Stile für das ganze Dokument (max. 24). Blöcke referenzieren sie über style. EN: named document styles (max 24); blocks reference them via style. Vollstaendige Stilfelder: frankki://blocks-guide. EN: complete style fields: frankki://blocks-guide."
    • changedInput schema / properties / templateMergeValues / description
      Previous value: -"Merge-Werte fuer die exakte Vorlagenversion. EN: Merge values for the exact template version."New value: +"Merge-Werte für die exakte Vorlagenversion. EN: Merge values for the exact template version."
  6. Changed1 schema field changed
    • changedInput schema / properties / deliveryType / enum
      Previous value: -[
      -  "standard",
      -  "einschreiben_einwurf",
      -  "einschreiben_uebergabe"
      -]New value: +[
      +  "standard",
      +  "einschreiben_einwurf",
      +  "einschreiben_uebergabe",
      +  "ch_b_post",
      +  "ch_a_post",
      +  "ch_einschreiben",
      +  "at_eco",
      +  "at_prio",
      +  "intl_standard",
      +  "intl_priority",
      +  "intl_express",
      +  "intl_tracked",
      +  "intl_registered"
      +]
  7. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Annotations (non-read-only, destructive, open-world) only signal that this is a mutating external action; the description adds the substance: dryRun is free and returns price, page-1 image and a checks list, a real send waits for human approval, autopilot releases template letters after 10 minutes, wallet funds are reserved at submit with INSUFFICIENT_FUNDS on no cover, and PRICE_CHANGED/PDF_LAYOUT_INVALID failure modes.

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

Conciseness3/5

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

The German portion is front-loaded and every sentence carries real information, but the full English translation repeats it verbatim, roughly doubling length with no added signal. For a 44-parameter tool that is a significant token cost the agent pays twice.

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

Completeness4/5

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

Given 44 parameters, nested objects, no output schema and 59% coverage, the description does heavy lifting on workflow, error codes and idempotency, so an agent can call it correctly for the main paths. It is still not complete for the many unannotated scalar parameters (scheduling, signatures, express, reference), so 4 rather than 5.

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 only 59%, but the description compensates on the decision-critical parameters: the exactly-one-of content/blocks rule, a concrete blocks example with schema reference, letterId vs inline, pdfStorageKey alongside printed recipient fields, and approvalMode behaviour. Undocumented parameters (express, subject, auditTag, reasoning, presetName, scheduledAt, signatureId, recipient fields) get no help anywhere, which caps this below 5.

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?

States a specific verb and resource (sends a letter by post) plus the internal pipeline: validates sender/recipient/AVV/limits, creates PDF, calculates price. It also immediately distinguishes the two content paths (letterId draft vs inline content/blocks) and names siblings it is not (letter_upload_pdf, letter_create_draft, shipping_quote).

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 routing: deadline letters (Mahnung/Kündigung/Mieterhöhung) go via Einschreiben with shipping_quote; a finished own PDF goes through letter_upload_pdf first; a draft without wallet cover uses letter_create_draft; approval state is checked via order_status/order_cancel; mcp_health reports which approval path applies. Alternatives and the conditions selecting them are named directly.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.