Skip to main content
Glama

Briefentwurf anlegen

letter_create_draft

Legt einen Briefentwurf an: erstellt eine Vorschau-PDF im hinterlegten Briefdesign (nur der Brieftext), speichert den Entwurf und liefert Seitenzahl, Vorschau-Link (24 Stunden gültig) und eine unverbindliche Kostenvorschau. Der Entwurf bleibt kostenfrei liegen, bis er versendet wird. Der Brieftext ist entweder 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 inkl. styleDefs und Limits: MCP-Ressource frankki://blocks-guide. Die ersten Seiten kommen als Bild zurück und zeigen Betreff, Anschrift im Adressfenster, Absender, Datum und Umbrüche so, wie sie gedruckt werden. Die eingebettete Karte ist die Vorschau für den Menschen; PDF-Link und Brieftext stehen zusätzlich im Ergebnis, für reine Textansichten. Gemeldete Auffälligkeiten stehen in warnings. Ein neuer Aufruf legt einen korrigierten Entwurf an; ein gedruckter Brief ist endgültig. 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. Nächster Schritt mit der zurückgegebenen letterId: letter_preview zeigt den Entwurf als Bild zum Nachbessern, order_send versendet ihn, letter_schedule versendet ihn zu einem späteren Zeitpunkt. EN: Creates a letter draft: produces a preview PDF in the stored letter design (letter body only), stores the draft and returns page count, preview link (valid for 24 hours) and a non-binding cost estimate. The draft stays free of charge until it is sent. The body is either 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 incl. styleDefs and limits: MCP resource frankki://blocks-guide. The first pages come back as images and show subject, address in the address window, sender, date and line breaks as they will print. The embedded card is the human preview; the PDF link and letter text are also in the result, for text-only views. Reported findings are in warnings. A new call creates a corrected draft; a printed letter is final. For a Mahnung, Kündigung, Mieterhöhung or other deadline letter, Einschreiben adds a proof of posting; shipping_quote returns its price. Next step with the returned letterId: letter_preview shows the draft as an image to refine it, order_send sends the draft, letter_schedule sends it at a later time.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "subject": "<subject>"
    },
    "name": "letter_create_draft"
  }
}

Input Schema

NameRequiredDescriptionDefault
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.
contentNoBrieftext als Fließtext. Genau eines von content und blocks. EN: Letter body as plain text. Exactly one of content and blocks.
subjectYes
designIdNoGespeichertes Briefdesign für diesen Brief. Es wird bereits in der Vorschau-PDF gerendert und am Entwurf gespeichert, sodass ein späterer Versand über die letterId es übernimmt (außer der Versand nennt selbst ein Design). Ohne Angabe gilt das Standard-Design des Absenderprofils, in der Vorschau wie beim Versand. EN: Saved letter design for this letter. It is already rendered into the preview PDF and stored on the draft so a later send by letterId inherits it (unless the send names its own design). If omitted, the sender profile default design applies, in the preview as well as on send.
languageNoStandard de. EN: Defaults to de.
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
signatureIdNoEine bestimmte gespeicherte Unterschrift an Stelle der zuerst hinterlegten. EN: A specific stored signature in place of the first one on file.
recipientZipNo
recipientCityNo
recipientNameNo
clientLetterIdNoIdempotenzschlüssel. Ein erneuter Aufruf mit demselben Wert UND derselben Nutzlast liefert denselben Entwurf, statt einen zweiten anzulegen. Ein anderer Brief braucht einen neuen Schlüssel: derselbe Schlüssel mit anderem Inhalt endet mit IDEMPOTENCY_CONFLICT, und es entsteht kein Entwurf. EN: Idempotency key. A repeat call with the same value AND the same payload returns the same draft instead of creating a second one. A different letter needs a new key: the same key with different content ends with IDEMPOTENCY_CONFLICT and creates no draft.
recipientStreetNo
senderAddressIdNo
senderProfileIdNoAbsenderprofil, mit dem später versendet wird. Für die Vorschau zählt daraus nur das Standard-Briefdesign. EN: Sender profile the letter will later be sent with. For the preview only its default letter design is used.
includeSignatureNotrue setzt die hinterlegte Unterschrift unter den Brieftext. Standard aus, wie beim Versand. EN: true places the stored signature under the letter text. Off by default, same as on send.
recipientCompanyNo
recipientCountryNo
recipientAddressIdNoEine gespeicherte Adresse aus dem Adressbuch (address_list) als Empfänger. Gleichwertig: recipientAddressInline oder die Felder recipientName bis recipientCountry wie bei order_send. EN: A saved address from the address book (address_list) as the recipient. Equivalent: recipientAddressInline or the fields recipientName to recipientCountry as on order_send.
recipientHouseNumberNo
recipientAddressInlineNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed8 schema fields changed
    • addedInput schema / properties / recipientAddressId
      Added value: +{
      +  "description": "Eine gespeicherte Adresse aus dem Adressbuch (address_list) als Empfänger. Gleichwertig: recipientAddressInline oder die Felder recipientName bis recipientCountry wie bei order_send. EN: A saved address from the address book (address_list) as the recipient. Equivalent: recipientAddressInline or the fields recipientName to recipientCountry as on order_send.",
      +  "format": "uuid",
      +  "type": "string"
      +}
    • addedInput schema / properties / recipientCity
      Added value: +{
      +  "type": "string"
      +}
    • addedInput schema / properties / recipientCompany
      Added value: +{
      +  "type": "string"
      +}
    • addedInput schema / properties / recipientCountry
      Added value: +{
      +  "type": "string"
      +}
    • addedInput schema / properties / recipientHouseNumber
      Added value: +{
      +  "type": "string"
      +}
    • addedInput schema / properties / recipientName
      Added value: +{
      +  "type": "string"
      +}
    • addedInput schema / properties / recipientStreet
      Added value: +{
      +  "type": "string"
      +}
    • addedInput schema / properties / recipientZip
      Added value: +{
      +  "type": "string"
      +}
  2. Changed8 schema fields changed
    • 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 / clientLetterId / description
      Previous value: -"Idempotenzschlüssel. Ein erneuter Aufruf mit demselben Wert UND derselben Nutzlast liefert denselben Entwurf, statt einen zweiten anzulegen. Für einen anderen Brief brauchst du einen neuen Schlüssel: derselbe Schlüssel mit anderem Inhalt wird mit IDEMPOTENCY_CONFLICT abgelehnt, damit du keinen Brief für angelegt hältst, den es nicht gibt. EN: Idempotency key. A repeat call with the same value AND the same payload returns the same draft instead of creating a second one. A different letter needs a new key: the same key with different content is refused with IDEMPOTENCY_CONFLICT, so you never believe a letter exists that does not."New value: +"Idempotenzschlüssel. Ein erneuter Aufruf mit demselben Wert UND derselben Nutzlast liefert denselben Entwurf, statt einen zweiten anzulegen. Ein anderer Brief braucht einen neuen Schlüssel: derselbe Schlüssel mit anderem Inhalt endet mit IDEMPOTENCY_CONFLICT, und es entsteht kein Entwurf. EN: Idempotency key. A repeat call with the same value AND the same payload returns the same draft instead of creating a second one. A different letter needs a new key: the same key with different content ends with IDEMPOTENCY_CONFLICT and creates no draft."
    • 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 Brief verwenden. Es wird bereits in der Vorschau-PDF gerendert und am Entwurf gespeichert, sodass ein späterer Versand über die letterId es übernimmt (außer der Versand nennt selbst ein Design). Ohne Angabe gilt das Standard-Design des Absenderprofils, in der Vorschau wie beim Versand. EN: Use a saved letter design for this letter. It is already rendered into the preview PDF and stored on the draft so a later send by letterId inherits it (unless the send names its own design). If omitted, the sender profile default design applies, in the preview as well as on send."New value: +"Gespeichertes Briefdesign für diesen Brief. Es wird bereits in der Vorschau-PDF gerendert und am Entwurf gespeichert, sodass ein späterer Versand über die letterId es übernimmt (außer der Versand nennt selbst ein Design). Ohne Angabe gilt das Standard-Design des Absenderprofils, in der Vorschau wie beim Versand. EN: Saved letter design for this letter. It is already rendered into the preview PDF and stored on the draft so a later send by letterId inherits it (unless the send names its own design). If omitted, the sender profile default design applies, in the preview as well as on send."
    • changedInput schema / properties / includeSignature / description
      Previous value: -"Hinterlegte Unterschrift unter den Brieftext setzen. Standard aus, wie beim Versand. EN: Place the stored signature under the letter text. Off by default, same as on send."New value: +"true setzt die hinterlegte Unterschrift unter den Brieftext. Standard aus, wie beim Versand. EN: true places the stored signature under the letter text. Off by default, same as on send."
    • 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 / signatureId / description
      Previous value: -"Eine bestimmte gespeicherte Unterschrift verwenden statt der zuerst hinterlegten. EN: Use a specific stored signature instead of the first one on file."New value: +"Eine bestimmte gespeicherte Unterschrift an Stelle der zuerst hinterlegten. EN: A specific stored signature in place of the first one on file."
    • 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. Changed7 schema fields changed
    • 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 / clientLetterId / description
      Previous value: -"Idempotenzschluessel. Ein erneuter Aufruf mit demselben Wert UND derselben Nutzlast liefert denselben Entwurf, statt einen zweiten anzulegen. Fuer einen anderen Brief brauchst du einen neuen Schluessel: derselbe Schluessel mit anderem Inhalt wird mit IDEMPOTENCY_CONFLICT abgelehnt, damit du keinen Brief fuer angelegt haeltst, den es nicht gibt. EN: Idempotency key. A repeat call with the same value AND the same payload returns the same draft instead of creating a second one. A different letter needs a new key: the same key with different content is refused with IDEMPOTENCY_CONFLICT, so you never believe a letter exists that does not."New value: +"Idempotenzschlüssel. Ein erneuter Aufruf mit demselben Wert UND derselben Nutzlast liefert denselben Entwurf, statt einen zweiten anzulegen. Für einen anderen Brief brauchst du einen neuen Schlüssel: derselbe Schlüssel mit anderem Inhalt wird mit IDEMPOTENCY_CONFLICT abgelehnt, damit du keinen Brief für angelegt hältst, den es nicht gibt. EN: Idempotency key. A repeat call with the same value AND the same payload returns the same draft instead of creating a second one. A different letter needs a new key: the same key with different content is refused with IDEMPOTENCY_CONFLICT, so you never believe a letter exists that does not."
    • 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 / designId / description
      Previous value: -"Ein gespeichertes Briefdesign fuer diesen Brief verwenden. Es wird bereits in der Vorschau-PDF gerendert und am Entwurf gespeichert, sodass ein spaeterer Versand ueber die letterId es uebernimmt (ausser der Versand nennt selbst ein Design). Ohne Angabe gilt das Standard-Design des Absenderprofils, in der Vorschau wie beim Versand. EN: Use a saved letter design for this letter. It is already rendered into the preview PDF and stored on the draft so a later send by letterId inherits it (unless the send names its own design). If omitted, the sender profile default design applies, in the preview as well as on send."New value: +"Ein gespeichertes Briefdesign für diesen Brief verwenden. Es wird bereits in der Vorschau-PDF gerendert und am Entwurf gespeichert, sodass ein späterer Versand über die letterId es übernimmt (außer der Versand nennt selbst ein Design). Ohne Angabe gilt das Standard-Design des Absenderprofils, in der Vorschau wie beim Versand. EN: Use a saved letter design for this letter. It is already rendered into the preview PDF and stored on the draft so a later send by letterId inherits it (unless the send names its own design). If omitted, the sender profile default design applies, in the preview as well as on send."
    • 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 / senderProfileId / description
      Previous value: -"Absenderprofil, mit dem spaeter versendet wird. Fuer die Vorschau zaehlt daraus nur das Standard-Briefdesign. EN: Sender profile the letter will later be sent with. For the preview only its default letter design is used."New value: +"Absenderprofil, mit dem später versendet wird. Für die Vorschau zählt daraus nur das Standard-Briefdesign. EN: Sender profile the letter will later be sent with. For the preview only its default letter design is used."
    • 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."
  4. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Annotations declare a non-read-only but non-destructive operation, and the description adds substantial behavioral context: the draft stays free until sent, the preview link is valid for 24 hours, the cost estimate is non-binding, and a new call creates a corrected draft while a printed letter is final. It also discloses returned images and warnings, all without contradicting the annotations.

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 description is front-loaded and organized, with purpose first and next steps last. However, it duplicates the full content in German and English, including the long blocks example twice, which adds token weight without new information for an agent.

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 23 parameters, no output schema, and nested objects, the description is largely complete: it explains the returned page count, preview link, cost estimate, images, warnings, and letterId-based next steps. It still leaves some optional parameters undocumented, but the essential workflow and return behavior are covered.

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?

The description adds real meaning for the most complex parameters: content versus blocks exclusivity, a concrete blocks example, the frankki://blocks-guide resource, designId inheritance, and idempotency behavior via clientLetterId. However, with 23 parameters and only 48% schema coverage, some fields such as reasoning, presetName, and several address fields remain unexplained.

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 a specific verb and resource: it creates a letter draft, renders a preview PDF, stores the draft, and returns page count, preview link, and cost estimate. It also distinguishes this tool from siblings such as letter_preview, order_send, and letter_schedule, so an agent can identify its role without opening the schema.

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?

It explicitly states when to use this tool and what to use next: letter_preview for refinement, order_send for sending, and letter_schedule for deferred sending. It also routes deadline letters (Mahnung, Kündigung, Mieterhöhung) to Einschreiben and shipping_quote for pricing, which is clear alternative guidance.

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.