Skip to main content
Glama
sevdesk-mcp

sevdesk-mcp

by joosthel

Correct a draft voucher

sevdesk_update_draft_voucher

Correct a draft voucher's date, document number, supplier, tax rule, and positions, then optionally finalize it to open status for transaction linking.

Instructions

Correct a draft voucher (status 50, Entwurf): date, document number, supplier name, tax rule and the positions (amounts, tax rate, booking account). positions replaces all positions: give the full new list; existing positions are reused in order (they keep their booking account unless accountDatevId is given), extra old ones are deleted. Example: gross 214.20 booked at 0 % -> positions [{sumNet: 180, taxRate: 19}] gives 180.00 + 34.20 VAT = 214.20. Positions you do not replace are sent back as they were entered, net or gross. A new taxRuleId is checked against the voucher's side (expense or revenue) and its position rates. finalize=true also sets the voucher to open (100), needed before sevdesk_link_transaction; every position then needs a booking account. finalize is refused unless the server runs with SEVDESK_ALLOW_BOOKING=true; without it the draft can still be corrected. Refuses open, paid and enshrined vouchers; keeps the attached file; verifies sums and status afterwards. ⚠️ This tool can change data in sevDesk.

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": {
      "voucherId": "<voucherId>"
    },
    "name": "sevdesk_update_draft_voucher"
  }
}

Input Schema

NameRequiredDescriptionDefault
dryRunNoShow the request without sending it.
finalizeNoAlso set the voucher from draft (50) to open (100). Refused unless the server runs with SEVDESK_ALLOW_BOOKING=true.
positionsNoThe complete new list of positions.
taxRuleIdNoNew tax rule id, e.g. 9 (Vorsteuerabziehbare Aufwendungen).
voucherIdYesNumeric voucher id.
descriptionNoNew document number (Belegnummer).
voucherDateNoNew voucher date, yyyy-mm-dd or dd.mm.yyyy.
supplierNameNoNew supplier name.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.6.0

TDQS

A4.5/5.0
Behavior4/5

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

With annotations already declaring readOnly=false and openWorld=true, the description goes well beyond them: positions is a full replacement (extra old ones deleted), existing positions keep their booking account unless accountDatevId is given, the attached file is kept, and sums/status are verified afterwards. The one point of friction is that destructiveHint=false sits uneasily with the disclosed deletion of surplus positions, though this is a correction of a draft rather than data destruction, and the description is candid about it. The server-side SEVDESK_ALLOW_BOOKING gate is exactly the kind of context annotations cannot express.

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-loaded with purpose and scope, then behavior, then the caveat and the write warning at the end. Every sentence carries information, but the mid-section is a dense run-on of parenthetical clauses that takes effort to parse on first read. Slightly tighter grouping of the positions rules would earn a 5.

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?

For an 8-parameter mutation with no output schema, the description covers the prerequisites (status gate, booking-permission gate), the side effects (position replacement, tax rule validation), the post-conditions (sums and status verified, file retained), and the transactional warning. An agent has everything needed to decide and invoke correctly.

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

Parameters5/5

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

Schema coverage is already 100%, so a 3 is the floor, but the description adds substantial meaning the schema does not: positions replaces the whole list with order-based reuse, sumNet/sumGross must be consistent across positions, a new taxRuleId is validated against the voucher's expense/revenue side and the position rates, and finalize additionally requires a booking account per position. The worked example (gross 214.20 at 0% -> sumNet 180, taxRate 19 => 180.00 + 34.20 VAT = 214.20) resolves ambiguity between net and gross entry that the schema alone leaves open.

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?

Opens with a specific verb and resource ("Correct a draft voucher") and immediately pins the scope to status 50 (Entwurf), then enumerates the correctable fields: date, document number, supplier name, tax rule and positions. An agent can distinguish this from sevdesk_create_voucher or sevdesk_get_voucher 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?

Exclusion criteria are explicit: it refuses open, paid and enshrined vouchers, and finalize is refused without SEVDESK_ALLOW_BOOKING=true. It also names a downstream dependency (finalize=true is needed before sevdesk_link_transaction) and points to sevdesk_receipt_guidance for accountDatevId. What is missing is a direct pointer to the sibling to use instead when the voucher is not a draft; the agent must infer it.

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