Skip to main content
Glama

sevdesk MCP by usefulapi

by io.usefulapi
OverviewDiscussionsAdmin

Create a draft invoice

sevdesk_create_draft_invoice
Destructive

Create a normal invoice (type RE) with its line items, ALWAYS saved as a DRAFT (status 100): it is not sent, not booked and stays editable in sevdesk. contact_person_id is the sevdesk USER responsible for it — copy contactPerson.id from any existing invoice (sevdesk_get_invoice). Bookkeeping 2.0 accounts use tax_rule_id (1 = taxable sales in Germany, the usual choice); 1.0 accounts pass tax_type instead (check sevdesk_get_bookkeeping_system_version). sevdesk: POST /Invoice/Factory/saveInvoice.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
headerNoInvoice header/title line.
addressNoComplete recipient address with line breaks. Omit to leave it empty.
currencyNoISO-4217 currency code. Default EUR.EUR
show_netNoIf true (default), position prices are net.
tax_textNoVAT text printed on the invoice. Default 'Umsatzsteuer 19%'.Umsatzsteuer 19%
tax_typeNoBookkeeping 1.0 only — leave unset on 2.0 accounts.
foot_textNoText below the line items (some HTML allowed).
head_textNoText above the line items (some HTML allowed).
positionsYesLine items (at least one).
contact_idYesThe contact (customer)'s numeric id.
tax_rule_idNoBookkeeping 2.0 VAT rule id. 1 taxable sales (Umsatzsteuerpflichtige Umsätze), 2 exports, 3 intra-EU supplies, 4 tax-free §4 UStG, 5 reverse charge §13b, 11 small business §19 (Kleinunternehmer), 17 not taxable in Germany, 18-20 One Stop Shop, 21 reverse charge §18b. Default 1.1
time_to_payNoPayment term in days.
invoice_dateYesInvoice date as dd.mm.yyyy.
delivery_dateNoDelivery / service date as dd.mm.yyyy (must not be after invoice_date for a normal invoice).
small_settlementNoTrue if the account uses the small-business scheme (no VAT).
contact_person_idYesId of the sevdesk user (SevUser) acting as contact person — e.g. contactPerson.id of an existing invoice.
address_country_idNosevdesk StaticCountry id of the billing address (1 = Germany). Default 1.
customer_internal_noteNoReference / order number field.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
  2. First observed

TDQS

A4.5/5.0
Behavior5/5

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

Annotations only declare destructiveHint=true, so the description carries most of the behavioral burden and does so well: it discloses that the invoice is a draft, not sent, not booked, and stays editable, and clarifies that contact_person_id is a sevdesk USER rather than the customer. This is real context beyond the single hint and does not contradict it.

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 the core purpose and the draft-status constraint, then layers parameter tips and the raw endpoint for debugging. Dense but every clause earns its place; no filler or restatement 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 an 18-parameter mutation tool with no output schema, the description covers the critical behaviors (draft state, contact_person semantics, tax routing) while the 100%-covered schema handles the rest. It does not say what the call returns (e.g. the new invoice id), which is a minor gap since no output schema exists.

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, but the description adds genuine meaning: it disambiguates contact_person_id (a SevUser, not the contact) and explains the mutual-exclusivity logic between tax_rule_id (2.0) and tax_type (1.0). These clarifications beat what the schema alone conveys for the most confusing parameters.

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 a normal invoice (type RE)') and immediately pins down the output state ('ALWAYS saved as a DRAFT (status 100)'). This scope is distinctive and lets an agent distinguish it from read-only invoice siblings 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?

Gives actionable routing guidance: which upstream tools supply required values (sevdesk_get_invoice for contactPerson.id, sevdesk_get_bookkeeping_system_version for the bookkeeping version) and the tax_rule_id vs tax_type branch. It does not name an explicit 'when not to use' alternative for invoice creation, but no obvious sibling competes for that job.

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

All sevdesk MCP by usefulapi toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources