Skip to main content
Glama

MaxRechnung

Beleg ändern

update_sales_document

Tarif: ab Pro (darunter antwortet die API mit plan_required).

Beleg ändern

Ändert Felder; die Belegart steht fest (Umwandeln über POST /sales-documents/{id}/convert). Statuswechsel: PATCH /sales-documents/{id}/status. Auftragsbestätigungen und Lieferscheine bleiben in jedem Status änderbar — auch vorhandene in Pro. Angebote sind nur als Entwurf (draft) änderbar: ab sent antwortet der Aufruf mit 409 conflict; Änderungen an einem versendeten oder abgelehnten Angebot laufen über POST /sales-documents/{id}/revise (neue Fassung), ein angenommenes Angebot bleibt, wie es ist. Ein Body nur mit custom_fields ändert die eigenen Felder in jedem Status. Scope invoices:draft.

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": {
      "id": "<id>"
    },
    "name": "update_sales_document"
  }
}

Input Schema

NameRequiredDescriptionDefault
idYesInterne `id` des Belegs (UUID), nicht die Belegnummer. Zu einer Nummer (z. B. `AN-2026-0004`) liefert `GET /sales-documents?number=…` (MCP: `list_sales_documents` mit `number`) die `id`.
bodyNoJSON-Request-Body.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses plan gating (Pro/Business tiers returning `plan_required`), the exact conflict failure mode (`409` on non-draft quotes), the status-dependent editability rules per document type, and the required scope `invoices:draft`. These are precisely the operational behaviours an agent cannot get from the annotations or schema.

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?

The plan/error caveat is front-loaded and each clause carries real constraints (tier, conflict, immutability). Minor waste: the heading "Beleg ändern" duplicates the tool title, and the body mixes prose with endpoint paths and bold emphasis that slightly slows scanning.

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 a mutation tool with a large nested body schema and no output schema, the description covers the critical unknowns: tier requirements, which statuses are editable, what happens on conflict, and which operations belong to other endpoints. Remaining gaps (partial-update merge behaviour for fields other than custom_fields, response shape) are minor.

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 description coverage is 100%, so the baseline is 3; the description earns an extra point by explaining conditional body semantics that the schema does not — notably that a body containing only `custom_fields` patches those fields even on finalised invoices and locked quotes, while the document type itself is not settable here.

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?

"Ändert Felder; die Belegart steht fest" states a specific verb (field update) and resource (sales document), and immediately fences off the two neighbouring operations (conversion via POST /convert, status change via PATCH /status). An agent can tell this apart from update_sales_document_status and convert_sales_document without opening either 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?

Strong conditional guidance: quotes are editable only while `draft`, a `sent`/rejected quote returns 409 and must be changed via the revise endpoint, accepted quotes are immutable, and a `custom_fields`-only body works in every status. The only shortfall is that alternatives are named as REST endpoints rather than the MCP sibling tools, so the agent must map `POST /sales-documents/{id}/status` to update_sales_document_status itself.

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.

Resources