Skip to main content
Glama
Dev10x-Guru

ksef-mcp

by Dev10x-Guru
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

synchronise_invoices

Fetch, decrypt, and archive every KSeF invoice package completed since the last run, resuming unfinished downloads and avoiding duplicates.

Instructions

Fetch, decrypt and archive every invoice package KSeF finished since the last run.

Takes no arguments on purpose. The date window, the package size and how many packages to ask for are decided by KSeF and by the hourly allowance, never by the caller: an agent driving them spends a twenty-per-hour budget in two minutes and the Ministry reads the pattern as working around a limit.

Safe to call again. A package still being built, or one fetched but not yet stored, stays recorded on disk with its key, so a second call continues it instead of asking for it twice. An invoice already in the archive is reported under already_held rather than downloaded again.

Reports where the invoices landed and which KSeF numbers arrived. It never returns invoice content: an FA(2)/FA(3) document holds a counterparty's personal data, and reading one means opening the file this tool names.

session_ceilings says how much one session may carry and, in assumed, whether KSeF granted those figures or the conservative fallback is in force because the registry answered about limits in a shape that could not be read. An assumed ceiling is a different event from a granted one, and the message says so in as many words.

correlation names this call in the technical journal on stderr. Quote it when reporting a failure: it is what lets the whole pass be reconstructed without running the synchronisation again out of twenty exports an hour.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault

No arguments

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
nipYes
messageYes
warningsNo
state_fileYes
correlationYes
environmentYes
subject_rolesYes
pending_exportsYes
session_ceilingsYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed11 schema fields changedv0.3.4
    • addedOutput schema / $defs / SessionCeilingsResult
      Added value: +{
+  "description": "How much one session may carry, and whether KSeF granted it (GH-118).",
+  "properties": {
+    "assumed": {
+      "title": "Assumed",
+      "type": "boolean"
+    },
+    "max_invoice_megabytes": {
+      "title": "Max Invoice Megabytes",
+      "type": "integer"
+    },
+    "max_invoice_with_attachment_megabytes": {
+      "title": "Max Invoice With Attachment Megabytes",
+      "type": "integer"
+    },
+    "max_invoices_per_session": {
+      "title": "Max Invoices Per Session",
+      "type": "integer"
+    },
+    "message": {
+      "title": "Message",
+      "type": "string"
+    }
+  },
+  "required": [
+    "assumed",
+    "message",
+    "max_invoice_megabytes",
+    "max_invoice_with_attachment_megabytes",
+    "max_invoices_per_session"
+  ],
+  "title": "SessionCeilingsResult",
+  "type": "object"
+}
    • addedOutput schema / $defs / SubjectRoleResult
      Added value: +{
+  "description": "Paths and KSeF numbers for one subject type. Never an invoice body (D-011).",
+  "properties": {
+    "already_held": {
+      "items": {
+        "type": "string"
+      },
+      "title": "Already Held",
+      "type": "array"
+    },
+    "archive_directory": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "title": "Archive Directory"
+    },
+    "archived": {
+      "items": {
+        "type": "string"
+      },
+      "title": "Archived",
+      "type": "array"
+    },
+    "invoice_count": {
+      "title": "Invoice Count",
+      "type": "integer"
+    },
+    "message": {
+      "title": "Message",
+      "type": "string"
+    },
+    "outcome": {
+      "title": "Outcome",
+      "type": "string"
+    },
+    "part_count": {
+      "title": "Part Count",
+      "type": "integer"
+    },
+    "subject_role": {
+      "title": "Subject Role",
+      "type": "string"
+    },
+    "synchronised_up_to": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "title": "Synchronised Up To"
+    }
+  },
+  "required": [
+    "subject_role",
+    "outcome",
+    "message",
+    "invoice_count",
+    "part_count",
+    "synchronised_up_to",
+    "archived",
+    "already_held",
+    "archive_directory"
+  ],
+  "title": "SubjectRoleResult",
+  "type": "object"
+}
    • removedOutput schema / $defs / SubjectTypeResult
      Removed value: -{
-  "description": "Paths and KSeF numbers for one subject type. Never an invoice body (D-011).",
-  "properties": {
-    "already_held": {
-      "items": {
-        "type": "string"
-      },
-      "title": "Already Held",
-      "type": "array"
-    },
-    "archive_directory": {
-      "anyOf": [
-        {
-          "type": "string"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "title": "Archive Directory"
-    },
-    "archived": {
-      "items": {
-        "type": "string"
-      },
-      "title": "Archived",
-      "type": "array"
-    },
-    "detail": {
-      "title": "Detail",
-      "type": "string"
-    },
-    "invoice_count": {
-      "title": "Invoice Count",
-      "type": "integer"
-    },
-    "outcome": {
-      "title": "Outcome",
-      "type": "string"
-    },
-    "part_count": {
-      "title": "Part Count",
-      "type": "integer"
-    },
-    "subject_type": {
-      "title": "Subject Type",
-      "type": "string"
-    },
-    "synchronised_up_to": {
-      "anyOf": [
-        {
-          "type": "string"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "title": "Synchronised Up To"
-    }
-  },
-  "required": [
-    "subject_type",
-    "outcome",
-    "detail",
-    "invoice_count",
-    "part_count",
-    "synchronised_up_to",
-    "archived",
-    "already_held",
-    "archive_directory"
-  ],
-  "title": "SubjectTypeResult",
-  "type": "object"
-}
    • addedOutput schema / properties / correlation
      Added value: +{
+  "title": "Correlation",
+  "type": "string"
+}
    • addedOutput schema / properties / message
      Added value: +{
+  "title": "Message",
+  "type": "string"
+}
    • addedOutput schema / properties / nip
      Added value: +{
+  "title": "Nip",
+  "type": "string"
+}
    • addedOutput schema / properties / session_ceilings
      Added value: +{
+  "$ref": "#/$defs/SessionCeilingsResult"
+}
    • addedOutput schema / properties / subject_roles
      Added value: +{
+  "items": {
+    "$ref": "#/$defs/SubjectRoleResult"
+  },
+  "title": "Subject Roles",
+  "type": "array"
+}
    • removedOutput schema / properties / subject_types
      Removed value: -{
-  "items": {
-    "$ref": "#/$defs/SubjectTypeResult"
-  },
-  "title": "Subject Types",
-  "type": "array"
-}
    • addedOutput schema / properties / warnings
      Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "title": "Warnings",
+  "type": "array"
+}
    • changedOutput schema / required
      Previous value: -[
-  "environment",
-  "subject_types",
-  "pending_exports",
-  "state_file"
-]New value: +[
+  "nip",
+  "environment",
+  "message",
+  "subject_roles",
+  "pending_exports",
+  "state_file",
+  "session_ceilings",
+  "correlation"
+]
  2. Addedv0.3.0

TDQS

A4.8/5.0
Behavior5/5

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

With no annotations provided, the description carries the full burden, and it delivers: idempotent retry behavior, continuation of incomplete packages, already_held handling, refusal to return invoice content for data-protection reasons, session_ceilings semantics, and stderr correlation for failure tracing. This is far beyond the minimum expected.

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?

Although the description is long for a zero-parameter tool, every paragraph earns its place: purpose, argument rationale, idempotency, privacy, output fields, and failure correlation. It is front-loaded with the core action and uses backticked field names to structure operational details clearly.

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?

The description is complete for a complex, sensitive synchronisation tool. It explains output fields such as session_ceilings, assumed, already_held, and correlation, while the output schema covers return structure. There is no missing behavioral or safety information that an agent would need to invoke it correctly and safely.

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

Parameters5/5

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

The schema has zero properties, so the baseline is 4, but the description adds real meaning by explaining why no arguments are accepted and what would happen if an agent tried to drive the process manually. It turns an empty schema into an intentional design constraint.

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 description opens with a precise verb phrase: 'Fetch, decrypt and archive every invoice package KSeF finished since the last run.' This names the resource, the action, and the boundary of the operation. It also clarifies the deliberate lack of arguments, which sharply distinguishes it from sibling tools like list_recent_invoices and export_period_statement.

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 gives clear contextual guidance: this tool runs a KSeF-driven synchronisation since the last run, takes no caller-controlled parameters, and is safe to call again. It does not explicitly name sibling alternatives or state 'use X instead', but the usage context is strong enough for an agent to select it appropriately.

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