nkfix-mcp

Overview Schema Source Related Servers Discussions Admin

Rechnungen

list_invoices

Read-only

Retrieve property invoices filtered by year, property, or cost category, including amount, billing period, cost type, and receipt status for billing review.

Instructions

Rechnungen (Kosten) mit Betrag, Zeitraum, Kostenart und ob ein Beleg hinterlegt ist. Eine Rechnung zählt zu einem Jahr, wenn sich ihr Zeitraum mit dem Jahr überschneidet.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "list_invoices"
  }
}

Input Schema

Name	Required	Description
`year`	No	nur Rechnungen, deren Zeitraum dieses Jahr berührt
`property_id`	No	nur Rechnungen dieser Immobilie
`cost_category_id`	No	nur diese Kostenart

Output Schema

Name	Required	Description
`note`	No
`count`	Yes
`items`	Yes
`total`	Yes	Summe der vollen Rechnungsbeträge aller passenden Rechnungen, auch der weggelassenen; nicht zeitanteilig. Die Kosten eines Jahres je Kostenart liefert get_billing_year_status.
`omitted`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Nov 12, 2026

TDQS

A3.5/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the read-only nature needs no restatement, and the description correctly does not repeat it. What it adds is the year-overlap semantics, but that same statement is already present in the year parameter's schema description, so the net behavioral value beyond structured fields is small; ordering, default scope when no filters are supplied, and result size are unaddressed.

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?

Two short sentences with no filler, and the resource definition leads before the year-overlap clarification. The field enumeration ('Betrag, Zeitraum, Kostenart, Beleg') is somewhat redundant because an output schema already exists, which keeps it from a 5.

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 simple, fully optional-filter list tool with an output schema and read-only annotations, the definition covers the resource and the one surprising semantic (year overlap). Only the no-filter default scope and ordering are missing, which are minor for this complexity level.

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 100%, so year, property_id and cost_category_id are already documented, and the description's overlap sentence is a near-duplicate of the year parameter text. Baseline 3 applies since the schema does the heavy lifting and the description adds no format or edge-case detail (e.g. whether filters combine conjunctively).

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 makes clear this is an invoice (cost) listing and enumerates the returned attributes (amount, period, cost type, document attached), so an agent knows the resource unambiguously. It does not, however, distinguish itself from near-siblings such as list_invoice_documents or list_payments, which an agent could plausibly confuse with it.

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?

The overlap rule ('eine Rechnung zählt zu einem Jahr, wenn sich ihr Zeitraum mit dem Jahr überschneidet') is a genuine usage/semantics rule that tells an agent how the year filter behaves. There is no explicit guidance on when to call this versus the invoice-document or payment listings, so usage is only implied rather than directed.

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