Skip to main content
Glama
Dev10x-Guru

ksef-mcp

by Dev10x-Guru
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

review_new_invoices

Lists invoices accepted by KSeF since your last review, marking them as seen so they are not repeated. Uses the official acceptance date, not the seller's issue date.

Instructions

Report the invoices that have arrived since a person was last shown any.

This is the question the free Ministry application cannot answer: it lists what is there, never what is new since somebody last looked. The comparison is against a ledger of KSeF numbers already reported by this tool, kept on disk per subject and per environment, so it survives restarts.

The window is the last ninety days, dated by acceptance in KSeF rather than by the seller's issue date — an invoice issued in March and accepted yesterday is new to the reader, and a window dated by issue date would not contain it. Both ends are fixed, so asking again within the same hour is answered from disk and spends nothing from twenty metadata queries an hour.

received_on per invoice is the day KSeF assigned the number, read off the number itself. It is independent of when this tool fetched anything, and it is not the seller's issue date, which is reported separately.

KSeF has no notion of a closed period and will not stop an invoice from landing in a month already filed, so earlier_month_count counts the new invoices whose number was assigned before the current month. That is a signal to look, never a statement that an invoice belongs to any period — the tax treatment is the reader's decision and this tool does not make it.

Invoices listed individually are recorded as shown, and the next call does not repeat them. Above the threshold the rows are dropped, and then nothing is recorded, because nobody saw them — marked_as_reviewed says which of the two happened. Metadata only: an FA(2)/FA(3) body holds a counterparty's personal data and never enters this answer.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault

No arguments

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
nipYes
messageYes
warningsNo
period_toYes
thresholdYes
environmentYes
ledger_fileYes
period_fromYes
subject_rolesYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed7 schema fields changedv0.3.4
    • removedOutput schema / $defs / DirectionReviewResult
      Removed value: -{
-  "properties": {
-    "complete": {
-      "title": "Complete",
-      "type": "boolean"
-    },
-    "earlier_month_count": {
-      "title": "Earlier Month Count",
-      "type": "integer"
-    },
-    "from_cache": {
-      "title": "From Cache",
-      "type": "boolean"
-    },
-    "gross_totals": {
-      "items": {
-        "$ref": "#/$defs/GrossTotal"
-      },
-      "title": "Gross Totals",
-      "type": "array"
-    },
-    "marked_as_reviewed": {
-      "title": "Marked As Reviewed",
-      "type": "boolean"
-    },
-    "message": {
-      "title": "Message",
-      "type": "string"
-    },
-    "new_count": {
-      "title": "New Count",
-      "type": "integer"
-    },
-    "new_invoices": {
-      "items": {
-        "$ref": "#/$defs/ReviewedInvoiceRow"
-      },
-      "title": "New Invoices",
-      "type": "array"
-    },
-    "outcome": {
-      "title": "Outcome",
-      "type": "string"
-    },
-    "queried_at": {
-      "anyOf": [
-        {
-          "type": "string"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "title": "Queried At"
-    },
-    "subject_type": {
-      "title": "Subject Type",
-      "type": "string"
-    }
-  },
-  "required": [
-    "subject_type",
-    "outcome",
-    "message",
-    "new_invoices",
-    "new_count",
-    "earlier_month_count",
-    "gross_totals",
-    "complete",
-    "marked_as_reviewed",
-    "queried_at",
-    "from_cache"
-  ],
-  "title": "DirectionReviewResult",
-  "type": "object"
-}
    • addedOutput schema / $defs / SubjectRoleReviewResult
      Added value: +{
+  "properties": {
+    "complete": {
+      "title": "Complete",
+      "type": "boolean"
+    },
+    "earlier_month_count": {
+      "title": "Earlier Month Count",
+      "type": "integer"
+    },
+    "from_cache": {
+      "title": "From Cache",
+      "type": "boolean"
+    },
+    "gross_totals": {
+      "items": {
+        "$ref": "#/$defs/GrossTotal"
+      },
+      "title": "Gross Totals",
+      "type": "array"
+    },
+    "marked_as_reviewed": {
+      "title": "Marked As Reviewed",
+      "type": "boolean"
+    },
+    "message": {
+      "title": "Message",
+      "type": "string"
+    },
+    "new_count": {
+      "title": "New Count",
+      "type": "integer"
+    },
+    "new_invoices": {
+      "items": {
+        "$ref": "#/$defs/ReviewedInvoiceRow"
+      },
+      "title": "New Invoices",
+      "type": "array"
+    },
+    "outcome": {
+      "title": "Outcome",
+      "type": "string"
+    },
+    "queried_at": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "title": "Queried At"
+    },
+    "subject_role": {
+      "title": "Subject Role",
+      "type": "string"
+    }
+  },
+  "required": [
+    "subject_role",
+    "outcome",
+    "message",
+    "new_invoices",
+    "new_count",
+    "earlier_month_count",
+    "gross_totals",
+    "complete",
+    "marked_as_reviewed",
+    "queried_at",
+    "from_cache"
+  ],
+  "title": "SubjectRoleReviewResult",
+  "type": "object"
+}
    • addedOutput schema / properties / message
      Added value: +{
+  "title": "Message",
+  "type": "string"
+}
    • addedOutput schema / properties / subject_roles
      Added value: +{
+  "items": {
+    "$ref": "#/$defs/SubjectRoleReviewResult"
+  },
+  "title": "Subject Roles",
+  "type": "array"
+}
    • removedOutput schema / properties / subject_types
      Removed value: -{
-  "items": {
-    "$ref": "#/$defs/DirectionReviewResult"
-  },
-  "title": "Subject Types",
-  "type": "array"
-}
    • addedOutput schema / properties / warnings
      Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "title": "Warnings",
+  "type": "array"
+}
    • changedOutput schema / required
      Previous value: -[
-  "nip",
-  "environment",
-  "threshold",
-  "period_from",
-  "period_to",
-  "ledger_file",
-  "subject_types"
-]New value: +[
+  "nip",
+  "environment",
+  "message",
+  "threshold",
+  "period_from",
+  "period_to",
+  "ledger_file",
+  "subject_roles"
+]
  2. Addedv0.3.0

TDQS

A4.6/5.0
Behavior5/5

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

With no annotations, the description carries the full burden, and it does so thoroughly. It discloses persistence across restarts, the distinction between KSeF acceptance date and seller's issue date, the 20-requests-per-hour budget, the recording of shown invoices, the threshold-drop behavior, and the meaning of marked_as_reviewed. It also notes that personal data from FA(2)/FA(3) bodies never enters the answer.

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 purpose is front-loaded in the first sentence, and the following paragraphs are organized thematically. It is longer than strictly necessary, but each paragraph conveys meaningful nuance about timing, persistence, and tax-period interpretation, so the length earns its place.

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?

Despite having no annotations and no parameters, the description is complete enough for an agent to invoke the tool correctly and interpret its result. It explains what is recorded, what happens on repeat calls, what marked_as_reviewed indicates, and what data is excluded, while the output schema can carry structured return details.

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?

The tool has zero parameters and the input schema has no properties, so the baseline is 4. There are no parameters to clarify; the description does add useful context about the implicit per-subject and per-environment comparison, even though no arguments are needed.

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?

The first sentence states a specific verb and resource: 'Report the invoices that have arrived since a person was last shown any.' This clearly distinguishes the tool from a plain list of invoices and from sibling tools like list_recent_invoices by making the 'new since last viewed' criterion explicit.

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?

The description clearly explains when this tool is appropriate: when the user needs what is new since the last look, which the free Ministry application cannot answer. It also gives operational context such as the 90-day window, the on-disk ledger, and the metadata query budget. It stops short of explicitly naming sibling alternatives and stating 'use X instead,' so it misses a 5.

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

Deploy Server

Other Tools