nkfix-mcp

Overview Schema Source Related Servers Discussions Admin

Zählerstand erfassen

record_meter_reading

Records a meter reading in NebenkostenFix after validating it against previous readings and requests confirmation when inconsistencies or concerns arise.

Instructions

Legt in NebenkostenFix einen abgelesenen Zählerstand an (schreibt, ändert nichts Bestehendes). Vorher wird geprüft, ob er zu den bisherigen Ständen passt; bei Bedenken wird nachgefragt. Zähler selbst legt nur der Mensch an: gibt es keinen passenden Zähler, sag das, statt etwas anderes zu erfassen.

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": {
      "meter_id": "<meter_id>",
      "reading_date": "<reading_date>",
      "value": "<value>"
    },
    "name": "record_meter_reading"
  }
}

Input Schema

Name	Required	Description
`value`	Yes	abgelesener Stand (beim Zweitarifzähler: Haupttarif)
`meter_id`	Yes	ID des Zählers, siehe Werkzeug list_meters
`reading_date`	Yes	Datum als YYYY-MM-DD
`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.
`value_off_peak`	No	Nebentarif, nur bei Zweitarifzählern
`interim_reading`	No	Stand zum Datum eines Mieterwechsels (§ 9b HeizkostenV)

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

A4.3/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so safety is partly covered; the description still adds real value by disclosing a built-in consistency check against previous readings and a clarification loop before anything is written. It also discloses a boundary not visible in annotations: meters themselves are never created by this tool. It does not address repeat submissions or duplicate readings, which matters given idempotentHint=false.

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?

Three short sentences, front-loaded with the write action and its scope, then the verification flow, then the hard boundary. The parenthetical clarification earns its place by preventing misreading of 'anlegen' as an upsert.

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 mutating tool with a rich schema, full description coverage, and an output schema, the description supplies exactly what structured fields cannot: the pre-write validation behavior, the ask-before-proceeding rule, and the meter-creation boundary. Nothing needed to invoke it correctly is missing.

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 coverage is 100%, including the sensitive approval_code parameter with its own explicit usage restriction, so the schema carries the parameter burden. The description adds only the general sequencing idea ('bei Bedenken wird nachgefragt') and no syntax, format, or per-parameter meaning beyond that, so the baseline 3 applies.

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 ('Legt ... einen abgelesenen Zählerstand an') and immediately scopes it as create-only ('schreibt, ändert nichts Bestehendes'), which separates it from update-style siblings. An agent knows exactly what object is created and that existing data is untouched.

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 concrete preconditions and a when-not rule: if there is no matching meter, report that rather than recording something else, and ask the human when the reading doesn't fit prior values. It does not name a sibling tool (e.g. check_meter_reading or list_meters) explicitly, so the routing is described behaviorally rather than by alternative name.

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