nkfix-mcp

Overview Schema Source Related Servers Discussions Admin

Rechnung erfassen

record_invoice

Creates a property cost invoice in NebenkostenFix with amount, period, property, and cost category, optionally attaching a receipt file and prompting before duplicate entries.

Instructions

Legt in NebenkostenFix eine Rechnung (Kosten einer Immobilie) an, auf Wunsch mit dem Beleg als Datei (schreibt, ändert nichts Bestehendes). Gibt es schon eine Rechnung mit derselben Nummer oder mit gleicher Kostenart, gleichem Betrag, Zeitraum und Wohnung, wird vorher nachgefragt. Den Inhalt eines Belegs liest du selbst; NebenkostenFix hat keine Texterkennung.

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": {
      "property_id": "<property_id>",
      "cost_category_id": "<cost_category_id>",
      "amount": "<amount>",
      "start_date": "<start_date>",
      "end_date": "<end_date>"
    },
    "name": "record_invoice"
  }
}

Input Schema

Name	Required	Description
`amount`	Yes	Betrag in Euro mit höchstens zwei Nachkommastellen, z. B. "1500.00" oder "1.500,00"
`co2_cost`	No	CO2-Kosten auf der Brennstoffrechnung
`end_date`	Yes	Ende des Leistungszeitraums, YYYY-MM-DD
`base_price`	No	Betrag in Euro
`labor_cost`	No	Arbeitskosten nach § 35a EStG, nur mit section_35a_category
`start_date`	Yes	Beginn des Leistungszeitraums, YYYY-MM-DD
`description`	No
`property_id`	Yes	ID der Immobilie, siehe Werkzeug list_properties
`provider_id`	No	siehe Werkzeug list_providers
`apartment_id`	No	nur wenn die Rechnung allein eine Wohnung betrifft
`invoice_date`	No	Datum auf der Rechnung, YYYY-MM-DD
`receipt_path`	No	Original der Rechnung als Datei; wird hochgeladen und mit der Rechnung verknüpft. Steht die Rechnung auf einem Beleg mit mehreren Rechnungen: upload_invoice_document und invoice_document_id nutzen.
`approval_code`	No	Freigabecode aus einer vorigen Antwort mit saved=false. Nur mitschicken, nachdem du dem Menschen die Bedenken gezeigt hast und er dem Speichern ausdrücklich zugestimmt hat. Nie vorab und nie von dir aus.
`invoice_number`	No
`co2_emission_kg`	No
`cost_category_id`	Yes	ID der Kostenart, siehe Werkzeug list_cost_categories
`heating_cost_type`	No	bei Heizkosten: Posten nach § 7 Abs. 2 HeizkostenV
`heating_system_id`	No	bei Heizkosten: die Anlage, zusammen mit heating_cost_type
`invoice_document_id`	No	Beleg, auf dem diese Rechnung steht, siehe list_invoice_documents
`section_35a_category`	No	§ 35a EStG: haushaltsnahe Dienstleistung oder Handwerkerleistung, nur mit labor_cost

Output Schema

Name	Required	Description
`id`	Yes	ID des neuen Eintrags
`note`	Yes
`saved`	Yes
`concerns`	Yes	was gegen das Speichern sprach (auch wenn trotzdem gespeichert wurde)
`approval_code`	No	Code für den zweiten Aufruf, falls der Mensch trotz der Bedenken speichern will

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Nov 12, 2026

TDQS

A3.7/5.0

Behavior4/5

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

Beyond the annotations (destructiveHint=false, idempotentHint=false), the description discloses three real behavioural traits: it only creates and never modifies existing data, it performs a duplicate check on invoice number or on cost category/amount/period/apartment and asks before proceeding, and it has no OCR so the agent must read the receipt itself. It does not describe the saved=false/approval-code round trip, which is delegated entirely to the 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?

Three sentences, front-loaded with what the tool does, then the duplicate-confirmation behaviour, then the OCR caveat. Slightly dense with parentheticals, but every sentence carries information an agent needs.

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 20-parameter write tool with an output schema and annotations, the description covers the essentials: mutation scope, duplicate-confirmation flow, and the no-OCR constraint. Remaining gaps (receipt_path vs. invoice_document_id, heating-cost pairing) are covered by the schema, so the definition is close to complete.

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

Parameters3/5

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

Schema description coverage is 85% across 20 parameters, so the schema already carries the parameter burden. The description adds one meaningful semantic point — that receipt content is not parsed by the system — which changes how receipt_path is used, but it adds no field-level meaning beyond that, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: it creates an invoice (a property cost) in NebenkostenFix, optionally with the receipt file attached. That is clearly distinguishable from read-oriented siblings such as list_invoices. It stops short of explicitly naming an alternative (e.g. upload_invoice_document for multi-invoice receipts), which is left to 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 Guidelines3/5

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

Usage context is implied — you call it when you want to persist an invoice — and the duplicate case is described ('wird vorher nachgefragt'). However, the description never says when NOT to use it or which sibling to pick instead for multi-invoice receipts or pure document uploads; that routing only appears inside schema field text.

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