Skip to main content
Glama
Dev10x-Guru

ksef-mcp

by Dev10x-Guru
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

export_period_statement

Export a month of purchase invoices as a CSV file with KSeF details for accountants to forward via email.

Instructions

Write one month of purchase invoices as a CSV an accountant can forward.

period is a calendar month spelled YYYY-MM. The month is the unit a period is closed in, and both ends being fixed is what lets the same request be answered from disk instead of spending one of twenty metadata queries an hour a second time.

working_directory overrides the directory declared during onboarding for this one call. Whichever is used is created 0700 if it is new, is refused outright if it lies inside the cache or data root — those are internal storage and deleting statements must never reach the archive — and is reported in warnings when its path looks like a cloud sync folder, unless the taxpayer acknowledged that directory during onboarding.

The file holds ten columns, in this order: KSeF number, the seller's own invoice number, issue date, seller NIP, seller name, gross, net, VAT, currency, and a KOD I verification code. The code is composed from the seller NIP, the issue date and the SHA-256 of the archived invoice body; rows whose body is not in the archive yet say so instead of carrying a blank code.

Addresses, bank accounts, invoice lines and local paths are absent on purpose: this file is written to be attached to an e-mail. The paths are in this answer instead.

Amounts are written exactly as KSeF stated them — no rounding, no float anywhere on the path — with a comma as the decimal separator and a semicolon between fields, which is what a Polish spreadsheet expects. Sums are in this answer, per currency, and never one figure across several of them.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
periodYes
working_directoryNo

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
nipYes
pathYes
periodYes
messageYes
completeYes
warningsNo
row_countYes
from_cacheYes
queried_atYes
environmentYes
gross_totalsYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.3.4
    • changedOutput schema / required
      Previous value: -[
-  "nip",
-  "environment",
-  "period",
-  "path",
-  "row_count",
-  "gross_totals",
-  "complete",
-  "from_cache",
-  "queried_at",
-  "message",
-  "warnings"
-]New value: +[
+  "nip",
+  "environment",
+  "message",
+  "period",
+  "path",
+  "row_count",
+  "gross_totals",
+  "complete",
+  "from_cache",
+  "queried_at"
+]
  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 does so thoroughly: it discloses file creation with 0700 permissions, refusal inside cache/data roots, cloud-sync warnings, CSV column order, decimal/comma separators, absence of certain fields, exact KSeF amounts, and where paths and sums are reported. This is exceptionally transparent about side effects and output format.

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, every paragraph earns its place by covering a distinct concern: purpose, period semantics, directory behavior, CSV contents, and formatting rules. The primary purpose is front-loaded, and there is no redundant or filler text.

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 tool with two parameters, no annotations, and an output schema, the description is remarkably complete. It explains return-relevant details (paths and sums in the answer), file structure, edge cases for missing archive bodies, and constraints on the working directory. There is no meaningful gap an agent would need filled to invoke it correctly.

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?

Schema description coverage is 0%, so the description must fully explain both parameters. It does: `period` is defined as a YYYY-MM calendar month with a caching rationale, and `working_directory` is explained as a one-call override with creation, refusal, and warning behaviors. This far exceeds what the bare schema provides.

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, resource, and deliverable: 'Write one month of purchase invoices as a CSV an accountant can forward.' This clearly distinguishes the tool from siblings like render_invoice_pdf or list_recent_invoices, which address different outputs and workflows.

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 context on when this tool is appropriate: it exports a closed calendar month and can reuse disk-stored results instead of consuming metadata queries. It does not explicitly name sibling tools as alternatives or state when not to use it, but the usage context is unambiguous.

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