Skip to main content
Glama
joosthel

sevdesk-mcp

by joosthel
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Create a draft invoice

sevdesk_create_invoice

Creates an outgoing sevDesk invoice as a draft with line items, quantities, prices, and tax rates, so nothing is sent to a customer before review; supports dry-run preview.

Instructions

Create an outgoing invoice as a draft (status 50) — always a draft, so nothing reaches a customer without review in sevDesk. Positions carry name, quantity, price and tax rate; the contact's address is filled in automatically. Honors SEVDESK_DRY_RUN. ⚠️ This tool can change data in sevDesk.

Input Schema

NameRequiredDescriptionDefault
dryRunNoPreview the request without sending it.
headerNoOptional invoice header text.
currencyNoCurrency (default EUR).
contactIdYesNumeric id of the customer contact.
positionsYesInvoice line items.
taxRuleIdYesRevenue tax rule id — required, never guessed. 1 taxable domestic, 2 export, 3 intra-EU supply, 4 §4 exempt, 5 §13b, 11 §19 UStG (no VAT shown), 17 not taxable domestically, 18-20 One Stop Shop (per-position taxRate required), 21 §18b.
invoiceDateNoInvoice date, yyyy-mm-dd (default today).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv0.5.0
    • changedInput schema / properties / positions / items / properties / taxRate / description
      Previous value: -"VAT rate; defaults to 19, or 0 for Kleinunternehmer."New value: +"VAT rate; defaults to what the tax rule allows (19 for rule 1, 0 for 0%-only rules). Required for OSS rules."
    • changedInput schema / properties / taxRuleId / description
      Previous value: -"Revenue tax rule id (default 1, or 11 for Kleinunternehmer)."New value: +"Revenue tax rule id — required, never guessed. 1 taxable domestic, 2 export, 3 intra-EU supply, 4 §4 exempt, 5 §13b, 11 §19 UStG (no VAT shown), 17 not taxable domestically, 18-20 One Stop Shop (per-position taxRate required), 21 §18b."
    • changedInput schema / required
      Previous value: -[
-  "contactId",
-  "positions"
-]New value: +[
+  "contactId",
+  "taxRuleId",
+  "positions"
+]
  2. First observedv0.4.0

TDQS

A4.4/5.0
Behavior4/5

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

Annotations already declare readOnly=false and destructive=false, and the description earns credit for adding that the record is forced to draft status 50 and that SEVDESK_DRY_RUN is honored — real behavioral facts not in structured data. The 'can change data' warning is somewhat redundant with the annotations, and return details are absent.

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

Conciseness5/5

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

Two sentences plus a warning marker, with the draft-status constraint front-loaded. No filler or repetition of the title.

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?

For a mutating create tool the description covers safety posture (draft-only), dry-run behavior and key side effects, and annotations carry the rest. No output schema exists, so a description of the returned invoice id would have helped an agent know what to expect back.

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 100%, so the baseline is 3; the description goes further by summarizing what positions carry and disclosing that the contact's address is auto-filled, cross-linking contactId to a side effect. It doesn't touch dryRun or invoiceDate semantics, but the schema covers those well.

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 ('Create an outgoing invoice') plus the exact resulting state ('as a draft (status 50)'), which separates it cleanly from sevdesk_create_voucher (incoming) and sevdesk_mark_invoice_sent. An agent can pick this without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explains the operating context clearly — always a draft, nothing reaches the customer without review — which tells the agent when this tool fits. It stops short of naming an alternative (e.g. how to finalize/send afterwards), so it lacks explicit routing to siblings.

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

Deploy Server

Other Tools