{
  "openapi": "3.1.0",
  "info": {
    "title": "Centrum Finansowe AI Agent HUB — API agentów",
    "version": "1.1.2",
    "description": "REST odpowiednik serwera MCP: każde narzędzie panelu jako POST /tools/{nazwa}. Agent działa w imieniu zalogowanego użytkownika (OAuth 2.1 albo klucz API z panelu) i ma te same uprawnienia co on, we wszystkich swoich firmach albo w firmach wybranych przy tworzeniu klucza. Kwoty w złotych, daty RRRR-MM-DD.",
    "contact": {
      "name": "AI AGENT HUB P.S.A.",
      "email": "support@aiagenthub.pl",
      "url": "https://ksiegowosc.aiagenthub.pl/dla-agentow"
    }
  },
  "servers": [
    {
      "url": "https://ksiegowosc.aiagenthub.pl/api/v1"
    }
  ],
  "externalDocs": {
    "url": "https://ksiegowosc.aiagenthub.pl/dla-agentow",
    "description": "Jak podłączyć Claude, Hermes i innych agentów"
  },
  "security": [
    {
      "oauth2": [
        "accounting:read",
        "accounting:write"
      ]
    },
    {
      "apiKey": []
    }
  ],
  "tags": [
    {
      "name": "Konto i firmy"
    },
    {
      "name": "Dokumenty"
    },
    {
      "name": "Faktury i księgowanie"
    },
    {
      "name": "KSeF"
    },
    {
      "name": "Księgi w Systim"
    },
    {
      "name": "Uzgodnienie i naprawy"
    },
    {
      "name": "Kontrahenci"
    },
    {
      "name": "Integracje"
    },
    {
      "name": "Abonament"
    }
  ],
  "components": {
    "securitySchemes": {
      "oauth2": {
        "type": "oauth2",
        "description": "OAuth 2.1 z PKCE i dynamiczną rejestracją klienta (serwer OAuth Supabase projektu).",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://ekuxswlfswacpfetyfsh.supabase.co/auth/v1/oauth/authorize",
            "tokenUrl": "https://ksiegowosc.aiagenthub.pl/oauth/token",
            "refreshUrl": "https://ksiegowosc.aiagenthub.pl/oauth/token",
            "scopes": {
              "accounting:read": "Odczyt danych firm",
              "accounting:write": "Zmiany: faktury, księgowanie, KSeF, ustawienia"
            }
          }
        }
      },
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "cfa_…",
        "description": "Klucz API z panelu (https://ksiegowosc.aiagenthub.pl/dashboard/agents): wybrane firmy, odczyt albo odczyt i zmiany."
      }
    }
  },
  "paths": {
    "/status": {
      "get": {
        "operationId": "status",
        "summary": "Stan usługi",
        "security": [],
        "responses": {
          "200": {
            "description": "Usługa działa",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/tools": {
      "get": {
        "operationId": "listTools",
        "summary": "Lista narzędzi (to samo co tools/list w MCP)",
        "security": [],
        "responses": {
          "200": {
            "description": "Narzędzia z opisami i schematami wejścia"
          }
        }
      }
    },
    "/tools/list_companies": {
      "post": {
        "operationId": "list_companies",
        "summary": "Lista firm na koncie",
        "description": "Firmy, którymi zarządza połączone konto (jedno konto może prowadzić wiele firm, np. biuro rachunkowe). Zwraca id, nazwę, NIP, profil podatkowy i stan integracji (Systim, KSeF). Wywołaj najpierw — każde narzędzie działające na danych firmy przyjmuje company_id. Gdy użytkownik mówi o firmie nazwą albo NIP-em, dopasuj ją tutaj; przy niejasności zapytaj, której firmy dotyczy polecenie.",
        "tags": [
          "Konto i firmy"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": true,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": false
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/get_company": {
      "post": {
        "operationId": "get_company",
        "summary": "Ustawienia firmy",
        "description": "Pełna konfiguracja jednej firmy: dane, profil podatkowy (VAT, forma opodatkowania, okres VAT), domyślne płatności, szablony Systim, tryb wysyłki do KSeF, status w Białej Liście VAT i stan integracji. warnings to rzeczy w konfiguracji, które psują księgowanie (np. pełna księgowość bez schematów księgowania) — pokaż je użytkownikowi. Formę księgowości w samym Systim sprawdza systim_accounting_setup. Bez haseł i tokenów — tych serwer nigdy nie zwraca.",
        "tags": [
          "Konto i firmy"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": true,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": false
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "company_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID firmy z list_companies. Można pominąć, gdy konto (albo klucz agenta) ma dostęp tylko do jednej firmy."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/update_company": {
      "post": {
        "operationId": "update_company",
        "summary": "Zmień ustawienia firmy",
        "description": "Zmienia dane i konfigurację firmy. Podaj tylko pola do zmiany. Profil podatkowy (vat_payer, vat_exemption_type, vat_exemption_legal_basis, tax_form, ryczalt_rate, vat_period) decyduje o tym, jak księgowane są faktury — zmieniaj go tylko na wyraźne polecenie użytkownika i ustaw confirm_tax_profile: true, gdy użytkownik potwierdził poprawność profilu.",
        "tags": [
          "Konto i firmy"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": false,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": false
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "company_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID firmy z list_companies. Można pominąć, gdy konto (albo klucz agenta) ma dostęp tylko do jednej firmy."
                  },
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200
                  },
                  "tax_id": {
                    "type": "string",
                    "pattern": "^[0-9]{10}$",
                    "description": "NIP, 10 cyfr bez kresek."
                  },
                  "platform": {
                    "type": "string",
                    "maxLength": 100,
                    "description": "Platforma sprzedaży, np. Allegro, Shopify (opcjonalnie)."
                  },
                  "address": {
                    "type": "string",
                    "maxLength": 200
                  },
                  "postal_code": {
                    "type": "string",
                    "maxLength": 12
                  },
                  "city": {
                    "type": "string",
                    "maxLength": 100
                  },
                  "bank_account": {
                    "type": "string",
                    "maxLength": 40,
                    "description": "Numer rachunku do faktur (IBAN albo 26 cyfr)."
                  },
                  "default_vat_rate": {
                    "type": "string",
                    "enum": [
                      "23",
                      "8",
                      "5",
                      "0",
                      "zw",
                      "np",
                      "oo"
                    ]
                  },
                  "default_payment_method": {
                    "type": "string",
                    "enum": [
                      "przelew",
                      "gotówka",
                      "karta",
                      "pobranie",
                      "barter",
                      "rozliczenie saldami"
                    ]
                  },
                  "default_payment_days": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 365
                  },
                  "vat_payer": {
                    "type": "boolean",
                    "description": "Czy firma jest czynnym podatnikiem VAT."
                  },
                  "vat_exemption_type": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Rodzaj zwolnienia z VAT (gdy vat_payer = false), np. „podmiotowe”."
                  },
                  "vat_exemption_legal_basis": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 500
                  },
                  "tax_form": {
                    "type": "string",
                    "enum": [
                      "kpir",
                      "ryczalt",
                      "pelna"
                    ],
                    "description": "kpir = księga przychodów i rozchodów, ryczalt, pelna = pełna księgowość."
                  },
                  "ryczalt_rate": {
                    "type": [
                      "number",
                      "null"
                    ],
                    "enum": [
                      2,
                      3,
                      5.5,
                      8.5,
                      10,
                      12,
                      12.5,
                      14,
                      15,
                      17,
                      20,
                      null
                    ]
                  },
                  "vat_period": {
                    "type": "string",
                    "enum": [
                      "monthly",
                      "quarterly"
                    ]
                  },
                  "confirm_tax_profile": {
                    "type": "boolean",
                    "description": "true = użytkownik potwierdził profil podatkowy (zapisuje datę potwierdzenia)."
                  },
                  "systim_id_szablonu": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "ID szablonu faktury w Systim (nadpisuje domyślny)."
                  },
                  "systim_id_numeracji": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "ID serii numeracji w Systim."
                  },
                  "systim_id_szablonu_ksiegowania": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "ID szablonu księgowania sprzedaży (pełna księgowość)."
                  },
                  "systim_id_szablonu_ksiegowania_zakupu": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "ID szablonu księgowania zakupu (pełna księgowość)."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/create_company": {
      "post": {
        "operationId": "create_company",
        "summary": "Dodaj firmę",
        "description": "Dodaje nową firmę do konta. Najpierw sprawdź NIP narzędziem lookup_company_by_nip, żeby wpisać pełną nazwę z rejestru. Po dodaniu firma potrzebuje integracji (connect_systim, connect_ksef) i potwierdzenia profilu podatkowego (update_company).",
        "tags": [
          "Konto i firmy"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": false,
          "destructiveHint": false,
          "idempotentHint": false,
          "openWorldHint": false
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200
                  },
                  "tax_id": {
                    "type": "string",
                    "pattern": "^[0-9]{10}$",
                    "description": "NIP, 10 cyfr."
                  },
                  "platform": {
                    "type": "string",
                    "maxLength": 100
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/delete_company": {
      "post": {
        "operationId": "delete_company",
        "summary": "Usuń firmę",
        "description": "NIEODWRACALNE: usuwa firmę z panelu razem z jej dokumentami, kontrahentami i integracjami (dane w Systim i KSeF zostają). Wywołuj wyłącznie na wyraźne polecenie użytkownika; confirm_tax_id musi być NIP-em tej firmy, a confirm_name jej dokładną nazwą.",
        "tags": [
          "Konto i firmy"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": false,
          "destructiveHint": true,
          "idempotentHint": false,
          "openWorldHint": false
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "company_id",
                  "confirm_name"
                ],
                "properties": {
                  "company_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID firmy z list_companies. Można pominąć, gdy konto (albo klucz agenta) ma dostęp tylko do jednej firmy."
                  },
                  "confirm_name": {
                    "type": "string",
                    "description": "Dokładna nazwa usuwanej firmy."
                  },
                  "confirm_tax_id": {
                    "type": "string",
                    "description": "NIP usuwanej firmy (gdy firma ma NIP)."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/lookup_company_by_nip": {
      "post": {
        "operationId": "lookup_company_by_nip",
        "summary": "Sprawdź NIP w rejestrach",
        "description": "Dane firmy z Białej Listy VAT (MF) i rejestru NIP: nazwa, adres, status VAT, rachunki. Używaj przed dodaniem firmy albo kontrahenta.",
        "tags": [
          "Konto i firmy"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": true,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": true
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "nip"
                ],
                "properties": {
                  "nip": {
                    "type": "string",
                    "pattern": "^[0-9]{10}$",
                    "description": "NIP, 10 cyfr."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/check_vat_registry": {
      "post": {
        "operationId": "check_vat_registry",
        "summary": "Sprawdź firmę w Białej Liście VAT",
        "description": "Odpytuje Białą Listę VAT o status firmy z konta i zapisuje wynik przy firmie (vat_registry_status). Nie zmienia profilu podatkowego — przy niezgodności poinformuj użytkownika.",
        "tags": [
          "Konto i firmy"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": false,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": true
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "company_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID firmy z list_companies. Można pominąć, gdy konto (albo klucz agenta) ma dostęp tylko do jednej firmy."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/get_dashboard_summary": {
      "post": {
        "operationId": "get_dashboard_summary",
        "summary": "Podsumowanie finansów firmy",
        "description": "Liczby z pulpitu: przychody i koszty, należności i zobowiązania (także przeterminowane), VAT należny i do odliczenia, dokumenty do sprawdzenia, sprzedaż bez KSeF oraz zestawienie miesięczne.",
        "tags": [
          "Konto i firmy"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": true,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": false
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "company_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID firmy z list_companies. Można pominąć, gdy konto (albo klucz agenta) ma dostęp tylko do jednej firmy."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/get_profile": {
      "post": {
        "operationId": "get_profile",
        "summary": "Profil konta",
        "description": "Imię i nazwisko, e-mail, plan i stan abonamentu połączonego konta.",
        "tags": [
          "Konto i firmy"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": true,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": false
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/update_profile": {
      "post": {
        "operationId": "update_profile",
        "summary": "Zmień profil konta",
        "description": "Zmienia imię i nazwisko na koncie. Hasła, e-maila i 2FA agent nie zmienia — to robi użytkownik w panelu.",
        "tags": [
          "Konto i firmy"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": false,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": false
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "full_name"
                ],
                "properties": {
                  "full_name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 120
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/list_documents": {
      "post": {
        "operationId": "list_documents",
        "summary": "Lista dokumentów",
        "description": "Faktury sprzedażowe i kosztowe firmy, najnowsze pierwsze. Filtry: rodzaj, status (draft, ocr_review, ready, posted, failed…), źródło (ksef, systim, ocr, manual, stripe), zakres dat wystawienia albo sprzedaży, kontrahent, numer KSeF, fragment numeru. Zwraca kwoty w złotych, status księgowania, płatności i KSeF. To lista panelu — pełny rejestr KSeF (także faktury nie zaimportowane) daje list_ksef_register, a rejestry Systim systim_list_invoices.",
        "tags": [
          "Dokumenty"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": true,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": false
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "company_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID firmy z list_companies. Można pominąć, gdy konto (albo klucz agenta) ma dostęp tylko do jednej firmy."
                  },
                  "kind": {
                    "type": "string",
                    "enum": [
                      "all",
                      "sales",
                      "purchase"
                    ],
                    "default": "all"
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "draft",
                      "ocr_pending",
                      "ocr_review",
                      "validating",
                      "ready",
                      "posting",
                      "posted",
                      "failed"
                    ]
                  },
                  "source": {
                    "type": "string",
                    "enum": [
                      "ksef",
                      "systim",
                      "ocr",
                      "manual",
                      "stripe"
                    ]
                  },
                  "payment_status": {
                    "type": "string",
                    "enum": [
                      "unpaid",
                      "partial",
                      "paid"
                    ]
                  },
                  "date_field": {
                    "type": "string",
                    "enum": [
                      "issue",
                      "sale"
                    ],
                    "default": "issue",
                    "description": "Której daty dotyczą date_from/date_to: wystawienia albo sprzedaży."
                  },
                  "date_from": {
                    "type": "string",
                    "format": "date",
                    "description": "Data od (RRRR-MM-DD)"
                  },
                  "date_to": {
                    "type": "string",
                    "format": "date",
                    "description": "Data do (RRRR-MM-DD)"
                  },
                  "counterparty_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Tylko dokumenty tego kontrahenta."
                  },
                  "ksef_number": {
                    "type": "string",
                    "maxLength": 60,
                    "description": "Dokładny numer KSeF."
                  },
                  "search": {
                    "type": "string",
                    "maxLength": 60,
                    "description": "Fragment numeru faktury."
                  },
                  "limit": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 100,
                    "default": 25
                  },
                  "offset": {
                    "type": "integer",
                    "minimum": 0,
                    "default": 0
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/get_document": {
      "post": {
        "operationId": "get_document",
        "summary": "Szczegóły dokumentu",
        "description": "Jeden dokument z pozycjami, kontrahentem, uwagami walidacji, stanem księgowania, płatności i KSeF (numer KSeF, UPO, błąd odrzucenia).",
        "tags": [
          "Dokumenty"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": true,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": false
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "document_id"
                ],
                "properties": {
                  "document_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID dokumentu z list_documents."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/get_document_pdf": {
      "post": {
        "operationId": "get_document_pdf",
        "summary": "PDF dokumentu",
        "description": "Wydruk faktury jako PDF (z programu księgowego albo złożony z XML-a KSeF), zakodowany base64.",
        "tags": [
          "Dokumenty"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": true,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": true
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "document_id"
                ],
                "properties": {
                  "document_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID dokumentu z list_documents."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/upload_document": {
      "post": {
        "operationId": "upload_document",
        "summary": "Wgraj fakturę kosztową (OCR)",
        "description": "Wgrywa skan albo PDF faktury kosztowej i odczytuje go (OCR z AI): dostawca, numer, daty, kwoty, kategoria. Nie księguje — gdy wynik ma requires_review albo blokujące uwagi, pokaż je użytkownikowi, popraw przez update_document i dopiero wtedy wywołaj post_document. Maks. 10 MB, PDF/JPG/PNG/WEBP.",
        "tags": [
          "Dokumenty"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": false,
          "destructiveHint": false,
          "idempotentHint": false,
          "openWorldHint": true
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "file_name",
                  "content_base64"
                ],
                "properties": {
                  "company_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID firmy z list_companies. Można pominąć, gdy konto (albo klucz agenta) ma dostęp tylko do jednej firmy."
                  },
                  "file_name": {
                    "type": "string",
                    "maxLength": 200,
                    "description": "Nazwa pliku z rozszerzeniem, np. faktura-123.pdf."
                  },
                  "content_base64": {
                    "type": "string",
                    "description": "Zawartość pliku w base64 (bez prefiksu data:)."
                  },
                  "mime_type": {
                    "type": "string",
                    "enum": [
                      "application/pdf",
                      "image/jpeg",
                      "image/png",
                      "image/webp"
                    ]
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/update_document": {
      "post": {
        "operationId": "update_document",
        "summary": "Popraw dane dokumentu",
        "description": "Poprawia dane dokumentu, który NIE jest jeszcze zaksięgowany (status draft, ocr_review, ready albo failed): numer, daty, termin, metodę płatności, kategorię kosztu, opis, kontrahenta. Zaksięgowaną fakturę sprzedaży zmienia się przez edit_invoice albo correct_invoice. mark_ready: true przestawia dokument na „gotowy do księgowania”.",
        "tags": [
          "Dokumenty"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": false,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": false
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "document_id"
                ],
                "properties": {
                  "document_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID dokumentu z list_documents."
                  },
                  "invoice_number": {
                    "type": "string",
                    "maxLength": 100
                  },
                  "issue_date": {
                    "type": "string",
                    "format": "date",
                    "description": "Data wystawienia (RRRR-MM-DD)"
                  },
                  "sale_date": {
                    "type": "string",
                    "format": "date",
                    "description": "Data sprzedaży (RRRR-MM-DD)"
                  },
                  "due_date": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "date"
                  },
                  "payment_method": {
                    "type": "string",
                    "enum": [
                      "przelew",
                      "gotówka",
                      "karta",
                      "pobranie",
                      "barter",
                      "rozliczenie saldami"
                    ]
                  },
                  "systim_category_id": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 24,
                    "description": "Kategoria kosztu Systim (lista w opisie create_purchase_invoice)."
                  },
                  "description": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 500
                  },
                  "counterparty_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID kontrahenta z list_counterparties."
                  },
                  "mark_ready": {
                    "type": "boolean"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/void_document": {
      "post": {
        "operationId": "void_document",
        "summary": "Anuluj niezaksięgowany dokument",
        "description": "Oznacza w panelu jako anulowany dokument, który nie trafił do programu księgowego ani do KSeF (np. duplikat skanu). Zaksięgowany dokument wycofuje się przez unpost_document.",
        "tags": [
          "Dokumenty"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": false,
          "destructiveHint": true,
          "idempotentHint": false,
          "openWorldHint": false
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "document_id"
                ],
                "properties": {
                  "document_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID dokumentu z list_documents."
                  },
                  "reason": {
                    "type": "string",
                    "maxLength": 300
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/refresh_document": {
      "post": {
        "operationId": "refresh_document",
        "summary": "Odśwież dokument z programu księgowego",
        "description": "Pobiera z Systim aktualny stan jednego dokumentu. Dokument bez numeru KSeF: nadpisuje w panelu nagłówek, kwoty, kontrahenta, rozliczenie i pozycje stanem z Systim. Dokument z KSeF: treść faktury (numer, daty, kontrahent, netto/VAT/brutto, waluta, kurs, pozycje) ZOSTAJE z KSeF — Systim trzyma ją jako wartość księgową (zakup walutowy w złotych, faktura rozliczeniowa kwotą P_15), więc z Systim przychodzi tylko rozliczenie, termin i forma płatności oraz kategoria kosztu. Różnice zwraca w ksef_differences; kwotę porównuje po kursie z faktury (ROZ: z P_15), a rzeczywisty rozjazd zapisuje jako blokującą uwagę ksef_data_divergence. Nie poprawia faktury z KSeF — sprzedaż koryguje correct_invoice, zakup koryguje sprzedawca.",
        "tags": [
          "Dokumenty"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": false,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": true
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "document_id"
                ],
                "properties": {
                  "document_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID dokumentu z list_documents."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/import_from_systim": {
      "post": {
        "operationId": "import_from_systim",
        "summary": "Importuj dokumenty z Systim",
        "description": "Pobiera do panelu faktury wystawione albo zaewidencjonowane bezpośrednio w Systim w podanym okresie (domyślnie bieżący i poprzedni miesiąc). Nie zmienia niczego w Systim.",
        "tags": [
          "Dokumenty"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": false,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": true
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "company_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID firmy z list_companies. Można pominąć, gdy konto (albo klucz agenta) ma dostęp tylko do jednej firmy."
                  },
                  "from": {
                    "type": "string",
                    "format": "date",
                    "description": "Od (RRRR-MM-DD)"
                  },
                  "to": {
                    "type": "string",
                    "format": "date",
                    "description": "Do (RRRR-MM-DD)"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/preview_invoice": {
      "post": {
        "operationId": "preview_invoice",
        "summary": "Sprawdź fakturę przed wystawieniem",
        "description": "Walidacja faktury bez zapisywania: sumy per stawka, dane nabywcy, profil VAT firmy, prognoza numeru z Systim. Zwraca listę uwag (severity: blocking/warning/info). Wywołaj przed create_sales_invoice.",
        "tags": [
          "Faktury i księgowanie"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": true,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": true
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "kind",
                  "lines"
                ],
                "properties": {
                  "company_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID firmy z list_companies. Można pominąć, gdy konto (albo klucz agenta) ma dostęp tylko do jednej firmy."
                  },
                  "kind": {
                    "type": "string",
                    "enum": [
                      "sales",
                      "purchase"
                    ]
                  },
                  "counterparty_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID kontrahenta."
                  },
                  "issue_date": {
                    "type": "string",
                    "format": "date",
                    "description": "Data wystawienia (RRRR-MM-DD)"
                  },
                  "sale_date": {
                    "type": "string",
                    "format": "date",
                    "description": "Data sprzedaży (RRRR-MM-DD)"
                  },
                  "due_date": {
                    "type": "string",
                    "format": "date",
                    "description": "Termin płatności (RRRR-MM-DD)"
                  },
                  "invoice_number": {
                    "type": "string",
                    "description": "Numer faktury kosztowej (dla kind = purchase)."
                  },
                  "systim_category_id": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 24
                  },
                  "lines": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 100,
                    "items": {
                      "type": "object",
                      "required": [
                        "name",
                        "quantity",
                        "unit_net_price",
                        "vat_rate"
                      ],
                      "properties": {
                        "name": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 256,
                          "description": "Nazwa towaru lub usługi."
                        },
                        "quantity": {
                          "type": "number",
                          "exclusiveMinimum": 0,
                          "description": "Ilość, np. 1 albo 2.5."
                        },
                        "unit": {
                          "type": "string",
                          "maxLength": 16,
                          "description": "Jednostka, np. „szt.”, „usł.”, „godz.” (domyślnie „szt.”)."
                        },
                        "unit_net_price": {
                          "type": "number",
                          "description": "Cena jednostkowa NETTO w złotych, np. 199.00."
                        },
                        "vat_rate": {
                          "type": "string",
                          "enum": [
                            "23",
                            "8",
                            "5",
                            "0",
                            "zw",
                            "np",
                            "oo"
                          ],
                          "description": "Stawka VAT: 23, 8, 5, 0, zw (zwolniona), np (nie podlega), oo (odwrotne obciążenie)."
                        }
                      }
                    }
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/create_sales_invoice": {
      "post": {
        "operationId": "create_sales_invoice",
        "summary": "Wystaw fakturę sprzedaży",
        "description": "Tworzy fakturę sprzedaży w panelu. Z post: true (domyślnie) od razu księguje ją w programie księgowym (Systim nadaje numer) — to zapis w księgach klienta, więc przed wywołaniem pokaż użytkownikowi nabywcę, pozycje i kwoty. Wysyłka do KSeF to osobny krok: send_to_ksef. Daty domyślnie dziś, termin wg ustawień firmy. Faktura za prowizję albo inną usługę rozliczaną okresowo: sale_date = ostatni dzień okresu, którego dotyczy (okres wpisz w opis pozycji). Faktura opłacona (kompensata, wypłata): po zaksięgowaniu register_payment z faktyczną datą. Najpierw preview_invoice.",
        "tags": [
          "Faktury i księgowanie"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": false,
          "destructiveHint": false,
          "idempotentHint": false,
          "openWorldHint": true
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "counterparty_id",
                  "lines"
                ],
                "properties": {
                  "company_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID firmy z list_companies. Można pominąć, gdy konto (albo klucz agenta) ma dostęp tylko do jednej firmy."
                  },
                  "counterparty_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Nabywca — ID z list_counterparties albo create_counterparty."
                  },
                  "issue_date": {
                    "type": "string",
                    "format": "date",
                    "description": "Data wystawienia (RRRR-MM-DD)"
                  },
                  "sale_date": {
                    "type": "string",
                    "format": "date",
                    "description": "Data sprzedaży (usługa okresowa, np. prowizja: ostatni dzień okresu) (RRRR-MM-DD)"
                  },
                  "due_date": {
                    "type": "string",
                    "format": "date",
                    "description": "Termin płatności (RRRR-MM-DD)"
                  },
                  "payment_method": {
                    "type": "string",
                    "enum": [
                      "przelew",
                      "gotówka",
                      "karta",
                      "pobranie",
                      "barter",
                      "rozliczenie saldami"
                    ]
                  },
                  "lines": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 100,
                    "items": {
                      "type": "object",
                      "required": [
                        "name",
                        "quantity",
                        "unit_net_price",
                        "vat_rate"
                      ],
                      "properties": {
                        "name": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 256,
                          "description": "Nazwa towaru lub usługi."
                        },
                        "quantity": {
                          "type": "number",
                          "exclusiveMinimum": 0,
                          "description": "Ilość, np. 1 albo 2.5."
                        },
                        "unit": {
                          "type": "string",
                          "maxLength": 16,
                          "description": "Jednostka, np. „szt.”, „usł.”, „godz.” (domyślnie „szt.”)."
                        },
                        "unit_net_price": {
                          "type": "number",
                          "description": "Cena jednostkowa NETTO w złotych, np. 199.00."
                        },
                        "vat_rate": {
                          "type": "string",
                          "enum": [
                            "23",
                            "8",
                            "5",
                            "0",
                            "zw",
                            "np",
                            "oo"
                          ],
                          "description": "Stawka VAT: 23, 8, 5, 0, zw (zwolniona), np (nie podlega), oo (odwrotne obciążenie)."
                        }
                      }
                    }
                  },
                  "post": {
                    "type": "boolean",
                    "default": true,
                    "description": "false = zapisz jako gotowy do księgowania, bez wysyłania do Systim."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/create_purchase_invoice": {
      "post": {
        "operationId": "create_purchase_invoice",
        "summary": "Zaewidencjonuj fakturę kosztową",
        "description": "Ręczne wprowadzenie faktury kosztowej (bez skanu). Podaj dostawcę, numer, daty, kwoty i kategorię kosztu Systim: 1 towary handlowe, 2 koszty uboczne zakupu, 3 wynagrodzenia, 4 faktura zaliczkowa, 5 media i telekomunikacja, 6 pojazd (paliwo, serwis), 7 wyposażenie, 8 środki trwałe, 9 opłaty bankowe, 10 delegacja, 12 najem, 13 WNiP, 14 ulepszenie ŚT, 15 samochód osobowy, 16 materiały, 17 samochód ciężarowy, 18 leasing, 19 dowód wewnętrzny, 20 zakup od rolnika (RR), 21 inny wydatek, 22 usługi, 23 pro forma, 24 ulepszenie WNiP. Z post: true od razu księguje w Systim.",
        "tags": [
          "Faktury i księgowanie"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": false,
          "destructiveHint": false,
          "idempotentHint": false,
          "openWorldHint": true
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "counterparty_id",
                  "invoice_number",
                  "issue_date",
                  "systim_category_id",
                  "lines"
                ],
                "properties": {
                  "company_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID firmy z list_companies. Można pominąć, gdy konto (albo klucz agenta) ma dostęp tylko do jednej firmy."
                  },
                  "counterparty_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Dostawca — ID z list_counterparties."
                  },
                  "invoice_number": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100
                  },
                  "issue_date": {
                    "type": "string",
                    "format": "date",
                    "description": "Data wystawienia (RRRR-MM-DD)"
                  },
                  "due_date": {
                    "type": "string",
                    "format": "date",
                    "description": "Termin płatności (RRRR-MM-DD)"
                  },
                  "payment_method": {
                    "type": "string",
                    "enum": [
                      "przelew",
                      "gotówka",
                      "karta",
                      "pobranie",
                      "barter",
                      "rozliczenie saldami"
                    ]
                  },
                  "systim_category_id": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 24
                  },
                  "description": {
                    "type": "string",
                    "maxLength": 500
                  },
                  "lines": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 100,
                    "items": {
                      "type": "object",
                      "required": [
                        "name",
                        "quantity",
                        "unit_net_price",
                        "vat_rate"
                      ],
                      "properties": {
                        "name": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 256,
                          "description": "Nazwa towaru lub usługi."
                        },
                        "quantity": {
                          "type": "number",
                          "exclusiveMinimum": 0,
                          "description": "Ilość, np. 1 albo 2.5."
                        },
                        "unit": {
                          "type": "string",
                          "maxLength": 16,
                          "description": "Jednostka, np. „szt.”, „usł.”, „godz.” (domyślnie „szt.”)."
                        },
                        "unit_net_price": {
                          "type": "number",
                          "description": "Cena jednostkowa NETTO w złotych, np. 199.00."
                        },
                        "vat_rate": {
                          "type": "string",
                          "enum": [
                            "23",
                            "8",
                            "5",
                            "0",
                            "zw",
                            "np",
                            "oo"
                          ],
                          "description": "Stawka VAT: 23, 8, 5, 0, zw (zwolniona), np (nie podlega), oo (odwrotne obciążenie)."
                        }
                      }
                    }
                  },
                  "post": {
                    "type": "boolean",
                    "default": true
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/post_document": {
      "post": {
        "operationId": "post_document",
        "summary": "Zaksięguj dokument",
        "description": "Wysyła gotowy dokument (status ready albo failed) do programu księgowego (Systim). To zapis w księgach firmy — przed wywołaniem upewnij się, że użytkownik zatwierdził dane. Zwraca numer nadany przez Systim albo uwagi blokujące.",
        "tags": [
          "Faktury i księgowanie"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": false,
          "destructiveHint": false,
          "idempotentHint": false,
          "openWorldHint": true
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "document_id"
                ],
                "properties": {
                  "document_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID dokumentu z list_documents."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/unpost_document": {
      "post": {
        "operationId": "unpost_document",
        "summary": "Wycofaj dokument z księgowości",
        "description": "NIEODWRACALNE w Systim: usuwa z programu księgowego zaksięgowany dokument, jego płatności i zapisy w księdze, a w panelu oznacza go jako anulowany. Niedostępne dla faktury sprzedaży wysłanej już do KSeF (tam tylko correct_invoice). Wymaga powodu i wyraźnej zgody użytkownika.",
        "tags": [
          "Faktury i księgowanie"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": false,
          "destructiveHint": true,
          "idempotentHint": false,
          "openWorldHint": true
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "document_id",
                  "reason"
                ],
                "properties": {
                  "document_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID dokumentu z list_documents."
                  },
                  "reason": {
                    "type": "string",
                    "minLength": 3,
                    "maxLength": 300
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/register_payment": {
      "post": {
        "operationId": "register_payment",
        "summary": "Zarejestruj płatność",
        "description": "Rejestruje wpłatę (sprzedaż) albo zapłatę (koszt) — całą albo częściową — w programie księgowym i w panelu. Kwota w walucie dokumentu. paid_at to FAKTYCZNA data rozliczenia, nie dzisiejsza: prowizja rozliczona kompensatą (rozliczenie saldami) — ostatni dzień okresu, którego dotyczy; wypłata przelewem — dzień realizacji wypłaty (z potwierdzenia albo wyciągu). Gdy daty nie znasz, zapytaj użytkownika. Data trafia do KSeF jako DataZaplaty, więc rejestruj płatność przed send_to_ksef. Płatność rozlicza fakturę — nie jest drugim kosztem ani przychodem.",
        "tags": [
          "Faktury i księgowanie"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": false,
          "destructiveHint": false,
          "idempotentHint": false,
          "openWorldHint": true
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "document_id",
                  "amount",
                  "paid_at"
                ],
                "properties": {
                  "document_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID dokumentu z list_documents."
                  },
                  "amount": {
                    "type": "number",
                    "exclusiveMinimum": 0,
                    "description": "Kwota w walucie dokumentu, np. 1230.00."
                  },
                  "paid_at": {
                    "type": "string",
                    "format": "date",
                    "description": "Faktyczna data zapłaty lub rozliczenia (kompensata: koniec okresu; wypłata: dzień realizacji) (RRRR-MM-DD)"
                  },
                  "method": {
                    "type": "string",
                    "enum": [
                      "przelew",
                      "gotówka",
                      "karta",
                      "pobranie",
                      "barter",
                      "rozliczenie saldami"
                    ]
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/check_invoice_edit": {
      "post": {
        "operationId": "check_invoice_edit",
        "summary": "Czy fakturę można edytować",
        "description": "Sprawdza zaksięgowaną fakturę sprzedaży: czy jest w KSeF i co wolno z nią zrobić — edycję (edit_invoice) czy tylko korektę (correct_invoice).",
        "tags": [
          "Faktury i księgowanie"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": true,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": true
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "document_id"
                ],
                "properties": {
                  "document_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID dokumentu z list_documents."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/edit_invoice": {
      "post": {
        "operationId": "edit_invoice",
        "summary": "Edytuj zaksięgowaną fakturę sprzedaży",
        "description": "Zmienia fakturę sprzedaży w programie księgowym (daty, termin, płatność, pozycje), gdy check_invoice_edit zwrócił, że edycja jest dozwolona (faktura poza KSeF i niedoręczona). confirm_not_delivered: true potwierdza, że faktura nie trafiła jeszcze do nabywcy.",
        "tags": [
          "Faktury i księgowanie"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": false,
          "destructiveHint": false,
          "idempotentHint": false,
          "openWorldHint": true
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "document_id",
                  "confirm_not_delivered"
                ],
                "properties": {
                  "document_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID dokumentu z list_documents."
                  },
                  "confirm_not_delivered": {
                    "type": "boolean"
                  },
                  "issue_date": {
                    "type": "string",
                    "format": "date",
                    "description": "Data wystawienia (RRRR-MM-DD)"
                  },
                  "sale_date": {
                    "type": "string",
                    "format": "date",
                    "description": "Data sprzedaży (RRRR-MM-DD)"
                  },
                  "due_date": {
                    "type": "string",
                    "format": "date",
                    "description": "Termin płatności (RRRR-MM-DD)"
                  },
                  "payment_method": {
                    "type": "string",
                    "enum": [
                      "przelew",
                      "gotówka",
                      "karta",
                      "pobranie",
                      "barter",
                      "rozliczenie saldami"
                    ]
                  },
                  "lines": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 100,
                    "items": {
                      "type": "object",
                      "required": [
                        "name",
                        "quantity",
                        "unit_net_price",
                        "vat_rate"
                      ],
                      "properties": {
                        "name": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 256,
                          "description": "Nazwa towaru lub usługi."
                        },
                        "quantity": {
                          "type": "number",
                          "exclusiveMinimum": 0,
                          "description": "Ilość, np. 1 albo 2.5."
                        },
                        "unit": {
                          "type": "string",
                          "maxLength": 16,
                          "description": "Jednostka, np. „szt.”, „usł.”, „godz.” (domyślnie „szt.”)."
                        },
                        "unit_net_price": {
                          "type": "number",
                          "description": "Cena jednostkowa NETTO w złotych, np. 199.00."
                        },
                        "vat_rate": {
                          "type": "string",
                          "enum": [
                            "23",
                            "8",
                            "5",
                            "0",
                            "zw",
                            "np",
                            "oo"
                          ],
                          "description": "Stawka VAT: 23, 8, 5, 0, zw (zwolniona), np (nie podlega), oo (odwrotne obciążenie)."
                        }
                      }
                    }
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/correct_invoice": {
      "post": {
        "operationId": "correct_invoice",
        "summary": "Wystaw fakturę korygującą",
        "description": "Wystawia korektę zaksięgowanej faktury: nowy, numerowany dokument w programie księgowym. lines to pozycje PO korekcie (pełny stan, nie różnica). Korektę faktury z KSeF trzeba potem wysłać send_to_ksef.",
        "tags": [
          "Faktury i księgowanie"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": false,
          "destructiveHint": false,
          "idempotentHint": false,
          "openWorldHint": true
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "document_id",
                  "reason",
                  "lines"
                ],
                "properties": {
                  "document_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID dokumentu z list_documents."
                  },
                  "reason": {
                    "type": "string",
                    "minLength": 3,
                    "maxLength": 300,
                    "description": "Przyczyna korekty, np. „rabat potransakcyjny”."
                  },
                  "issue_date": {
                    "type": "string",
                    "format": "date",
                    "description": "Data wystawienia korekty (RRRR-MM-DD)"
                  },
                  "lines": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 100,
                    "items": {
                      "type": "object",
                      "required": [
                        "name",
                        "quantity",
                        "unit_net_price",
                        "vat_rate"
                      ],
                      "properties": {
                        "name": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 256,
                          "description": "Nazwa towaru lub usługi."
                        },
                        "quantity": {
                          "type": "number",
                          "exclusiveMinimum": 0,
                          "description": "Ilość, np. 1 albo 2.5."
                        },
                        "unit": {
                          "type": "string",
                          "maxLength": 16,
                          "description": "Jednostka, np. „szt.”, „usł.”, „godz.” (domyślnie „szt.”)."
                        },
                        "unit_net_price": {
                          "type": "number",
                          "description": "Cena jednostkowa NETTO w złotych, np. 199.00."
                        },
                        "vat_rate": {
                          "type": "string",
                          "enum": [
                            "23",
                            "8",
                            "5",
                            "0",
                            "zw",
                            "np",
                            "oo"
                          ],
                          "description": "Stawka VAT: 23, 8, 5, 0, zw (zwolniona), np (nie podlega), oo (odwrotne obciążenie)."
                        }
                      }
                    }
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/send_to_ksef": {
      "post": {
        "operationId": "send_to_ksef",
        "summary": "Wyślij fakturę do KSeF",
        "description": "NIEODWRACALNE: wystawia zaksięgowaną fakturę sprzedaży (albo korektę) w Krajowym Systemie e-Faktur. Faktury przyjętej przez KSeF nie da się usunąć — zmienia ją tylko korekta. Działa, gdy firma ma wysyłkę z panelu (get_company → ksef_sending_via = panel). Przed wywołaniem pokaż użytkownikowi numer, nabywcę, kwotę, datę sprzedaży i — przy fakturze opłaconej — datę zapłaty (get_document → paid_on; bez niej KSeF dostanie DataZaplaty = data wystawienia) i poczekaj na zgodę. Wynik potwierdź przez get_ksef_status.",
        "tags": [
          "KSeF"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": false,
          "destructiveHint": true,
          "idempotentHint": false,
          "openWorldHint": true
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "document_id"
                ],
                "properties": {
                  "document_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID dokumentu z list_documents."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/get_ksef_status": {
      "post": {
        "operationId": "get_ksef_status",
        "summary": "Status faktury w KSeF",
        "description": "Sprawdza w KSeF wynik wysyłki: numer KSeF i UPO albo powód odrzucenia. Zapisuje wynik przy dokumencie.",
        "tags": [
          "KSeF"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": false,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": true
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "document_id"
                ],
                "properties": {
                  "document_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID dokumentu z list_documents."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/import_from_ksef": {
      "post": {
        "operationId": "import_from_ksef",
        "summary": "Pobierz faktury z KSeF",
        "description": "Pobiera z KSeF faktury kosztowe i sprzedażowe firmy, których jeszcze nie ma w panelu. KSeF ma limit zapytań na godzinę — nie wywołuj w pętli.",
        "tags": [
          "KSeF"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": false,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": true
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "company_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID firmy z list_companies. Można pominąć, gdy konto (albo klucz agenta) ma dostęp tylko do jednej firmy."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/list_ksef_register": {
      "post": {
        "operationId": "list_ksef_register",
        "summary": "Rejestr KSeF firmy",
        "description": "Pełny rejestr faktur firmy w KSeF — zakupy i sprzedaż, także te, których nie ma w panelu. Czyta kopię rejestru u nas (bez zapytań do KSeF, bez tworzenia dokumentów). Filtry: kierunek, data wystawienia albo przyjęcia w KSeF, NIP sprzedawcy lub nabywcy, numer, rodzaj (Vat, Kor, Zal, Roz, KorZal), obecność w panelu. Stronicowanie: limit/offset, total i has_more. coverage mówi, za jaki okres pobranie z KSeF jest kompletne i kiedy ostatnio działało — bez tego „brak w rejestrze” nic nie znaczy. Kwoty w walucie faktury, *_pln w złotych.",
        "tags": [
          "KSeF"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": true,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": false
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "company_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID firmy z list_companies. Można pominąć, gdy konto (albo klucz agenta) ma dostęp tylko do jednej firmy."
                  },
                  "direction": {
                    "type": "string",
                    "enum": [
                      "all",
                      "purchase",
                      "sales"
                    ],
                    "default": "all"
                  },
                  "date_field": {
                    "type": "string",
                    "enum": [
                      "issue",
                      "acquisition"
                    ],
                    "default": "issue",
                    "description": "issue = data wystawienia, acquisition = data przyjęcia w KSeF."
                  },
                  "date_from": {
                    "type": "string",
                    "format": "date",
                    "description": "Data od (RRRR-MM-DD)"
                  },
                  "date_to": {
                    "type": "string",
                    "format": "date",
                    "description": "Data do (RRRR-MM-DD)"
                  },
                  "nip": {
                    "type": "string",
                    "pattern": "^[0-9]{10}$",
                    "description": "NIP sprzedawcy albo nabywcy."
                  },
                  "search": {
                    "type": "string",
                    "maxLength": 60,
                    "description": "Fragment numeru faktury albo numeru KSeF."
                  },
                  "invoice_type": {
                    "type": "string",
                    "maxLength": 20,
                    "description": "Rodzaj z metadanych KSeF: Vat, Kor, Zal, Roz, KorZal…"
                  },
                  "in_panel": {
                    "type": "string",
                    "enum": [
                      "all",
                      "missing",
                      "present"
                    ],
                    "default": "all",
                    "description": "missing = faktury bez dokumentu w panelu."
                  },
                  "limit": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 500,
                    "default": 100
                  },
                  "offset": {
                    "type": "integer",
                    "minimum": 0,
                    "default": 0
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/get_ksef_invoice": {
      "post": {
        "operationId": "get_ksef_invoice",
        "summary": "Faktura z KSeF: XML, PDF i UPO",
        "description": "Oryginalny XML faktury z KSeF (FA) po numerze KSeF, opcjonalnie wydruk PDF, adres weryfikacyjny i UPO. Pierwsze pobranie faktury, której XML-a jeszcze nie mamy, zużywa jedno zapytanie z limitu KSeF (64/h) — plik zostaje u nas, kolejne odczyty są darmowe. Nie tworzy dokumentu w panelu. UPO istnieje tylko dla faktur wysłanych z panelu: nabywca UPO nie dostaje, a faktury wysłane innym programem mają UPO u niego.",
        "tags": [
          "KSeF"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": true,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": true
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "ksef_number"
                ],
                "properties": {
                  "company_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID firmy z list_companies. Można pominąć, gdy konto (albo klucz agenta) ma dostęp tylko do jednej firmy."
                  },
                  "ksef_number": {
                    "type": "string",
                    "minLength": 10,
                    "maxLength": 60
                  },
                  "format": {
                    "type": "string",
                    "enum": [
                      "xml",
                      "pdf",
                      "both"
                    ],
                    "default": "xml"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/get_sync_status": {
      "post": {
        "operationId": "get_sync_status",
        "summary": "Stan pobierania i zgodności źródeł",
        "description": "Aktualność i kompletność danych: do kiedy pobrano KSeF (zakupy i sprzedaż osobno), od kiedy rejestr jest pełny, kiedy ostatnio działał import z Systim, ostatnie błędy, oraz liczniki rozjazdów panel↔Systim↔KSeF (brak w Systim, sprzedaż bez KSeF, tylko w KSeF, tylko w Systim). Wywołaj przed uzgadnianiem.",
        "tags": [
          "KSeF"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": true,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": false
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "company_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID firmy z list_companies. Można pominąć, gdy konto (albo klucz agenta) ma dostęp tylko do jednej firmy."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/list_sync_conflicts": {
      "post": {
        "operationId": "list_sync_conflicts",
        "summary": "Konflikty importu KSeF",
        "description": "Faktury z KSeF, których panel nie dopasował jednoznacznie do dokumentów — do wyjaśnienia z użytkownikiem.",
        "tags": [
          "KSeF"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": true,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": false
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "company_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID firmy z list_companies. Można pominąć, gdy konto (albo klucz agenta) ma dostęp tylko do jednej firmy."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/resolve_sync_conflict": {
      "post": {
        "operationId": "resolve_sync_conflict",
        "summary": "Zamknij konflikt importu",
        "description": "Zamyka zgłoszenie z list_sync_conflicts po decyzji użytkownika — jak przycisk w karcie Dokumenty. document_id wskazuje dokument, do którego faktura należy (pomiń, gdy żaden). Zgłoszenie zostaje jako ślad; kolejny przebieg importu przetworzy fakturę na nowo.",
        "tags": [
          "KSeF"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": false,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": false
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "conflict_id"
                ],
                "properties": {
                  "conflict_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID zgłoszenia z list_sync_conflicts."
                  },
                  "document_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Dokument, do którego należy faktura (opcjonalnie)."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/systim_accounting_setup": {
      "post": {
        "operationId": "systim_accounting_setup",
        "summary": "Forma księgowości w Systim",
        "description": "Sprawdza w samym Systim, czy firma ma pełną księgowość (lata obrachunkowe: id i daty), i porównuje z profilem w panelu (tax_form). Wywołaj, zanim zmienisz tax_form albo zaczniesz czytać księgę — nie zgaduj formy z nazwy spółki. Tylko odczyt.",
        "tags": [
          "Księgi w Systim"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": true,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": true
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "company_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID firmy z list_companies. Można pominąć, gdy konto (albo klucz agenta) ma dostęp tylko do jednej firmy."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/systim_list_invoices": {
      "post": {
        "operationId": "systim_list_invoices",
        "summary": "Rejestr faktur w Systim",
        "description": "Faktury sprzedaży albo zakupów wprost z Systim (nie z kopii w panelu), miesiąc po miesiącu. Sprzedaż Systim filtruje po dacie wystawienia, zakupy po dacie WPROWADZENIA do ewidencji (bywa ustawiana wstecz albo później). windows podaje liczność każdego miesiąca — listy Systim nie mają stronicowania, okno z podejrzanie okrągłą liczbą ma possibly_truncated. Pokazuje osobno systim_id faktury, kontrahenta, NIP i numer KSeF (gdy Systim go podaje). Nic nie importuje.",
        "tags": [
          "Księgi w Systim"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": true,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": true
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "kind"
                ],
                "properties": {
                  "company_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID firmy z list_companies. Można pominąć, gdy konto (albo klucz agenta) ma dostęp tylko do jednej firmy."
                  },
                  "kind": {
                    "type": "string",
                    "enum": [
                      "sales",
                      "purchase"
                    ]
                  },
                  "date_from": {
                    "type": "string",
                    "format": "date",
                    "description": "Od (domyślnie 1 stycznia bieżącego roku) (RRRR-MM-DD)"
                  },
                  "date_to": {
                    "type": "string",
                    "format": "date",
                    "description": "Do (domyślnie dziś) (RRRR-MM-DD)"
                  },
                  "include_raw": {
                    "type": "boolean",
                    "default": false,
                    "description": "Dołącz surowe wiersze Systim (wszystkie pola)."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/systim_list_ledger": {
      "post": {
        "operationId": "systim_list_ledger",
        "summary": "Księga w Systim: dziennik, KPiR, ryczałt",
        "description": "Wpisy księgi firmy z Systim w okresie: księgi handlowe (kh — dziennik z dekretami Wn/Ma), KPiR albo ewidencja ryczałtu. Domyślnie księga wg tax_form z panelu. with_decrees: true dociąga dekret każdego wpisu KH (konto, nazwa konta, kwota po stronie Wn/Ma) — wolniejsze, do 150 wpisów. Każdy wpis ma osobny id wpisu i — gdy Systim go podaje — id powiązanej faktury. fields_seen pokazuje pola, które przyszły z Systim. Nic nie zmienia.",
        "tags": [
          "Księgi w Systim"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": true,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": true
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "company_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID firmy z list_companies. Można pominąć, gdy konto (albo klucz agenta) ma dostęp tylko do jednej firmy."
                  },
                  "date_from": {
                    "type": "string",
                    "format": "date",
                    "description": "Od (RRRR-MM-DD)"
                  },
                  "date_to": {
                    "type": "string",
                    "format": "date",
                    "description": "Do (RRRR-MM-DD)"
                  },
                  "book": {
                    "type": "string",
                    "enum": [
                      "kh",
                      "kpir",
                      "ryczalt"
                    ],
                    "description": "kh = księgi handlowe (pełna księgowość)."
                  },
                  "with_decrees": {
                    "type": "boolean",
                    "default": false
                  },
                  "include_raw": {
                    "type": "boolean",
                    "default": false
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/systim_list_payments": {
      "post": {
        "operationId": "systim_list_payments",
        "summary": "Płatności w Systim",
        "description": "Płatności zarejestrowane w Systim w okresie (osobny systim_id płatności), z rodzajem: dokument sprzedaży, zakupu, inny przychód, inny rozchód. with_links: true dociąga, które faktury (systim_id faktury) i jaką kwotą płatność rozlicza — do 150 płatności. Płatność to rozliczenie, nie drugi koszt ani przychód. Systim nie ma osobnych rozrachunków; to jest najbliższe źródło.",
        "tags": [
          "Księgi w Systim"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": true,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": true
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "company_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID firmy z list_companies. Można pominąć, gdy konto (albo klucz agenta) ma dostęp tylko do jednej firmy."
                  },
                  "date_from": {
                    "type": "string",
                    "format": "date",
                    "description": "Data płatności od (RRRR-MM-DD)"
                  },
                  "date_to": {
                    "type": "string",
                    "format": "date",
                    "description": "Data płatności do (RRRR-MM-DD)"
                  },
                  "concerns": {
                    "type": "string",
                    "enum": [
                      "sales",
                      "purchase",
                      "other_income",
                      "other_expense"
                    ]
                  },
                  "with_links": {
                    "type": "boolean",
                    "default": false
                  },
                  "include_raw": {
                    "type": "boolean",
                    "default": false
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/systim_get_record": {
      "post": {
        "operationId": "systim_get_record",
        "summary": "Rekord z Systim",
        "description": "Jeden rekord wprost z Systim po jego ID: faktura sprzedaży albo zakupu (nagłówek i pozycje), wpis księgi (z dekretem Wn/Ma przy KH) albo płatność (z powiązanymi fakturami). Tylko odczyt.",
        "tags": [
          "Księgi w Systim"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": true,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": true
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "type",
                  "systim_id"
                ],
                "properties": {
                  "company_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID firmy z list_companies. Można pominąć, gdy konto (albo klucz agenta) ma dostęp tylko do jednej firmy."
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "sales_invoice",
                      "purchase_invoice",
                      "ledger_entry",
                      "payment"
                    ]
                  },
                  "systim_id": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 40
                  },
                  "book": {
                    "type": "string",
                    "enum": [
                      "kh",
                      "kpir",
                      "ryczalt"
                    ],
                    "description": "Dla ledger_entry (domyślnie wg tax_form)."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/systim_export_report": {
      "post": {
        "operationId": "systim_export_report",
        "summary": "Raport z Systim: JPK_KR, bilans, RZiS",
        "description": "Plik wygenerowany przez Systim: jpk_kr (pełna księgowość — dziennik, zapisy na kontach Wn/Ma i ZOiS za okres; summary zawiera konta z obrotami/saldem, czyli plan kont w zakresie, w jakim API go pokazuje), balance_sheet albo profit_and_loss (dla roku obrachunkowego — id z systim_accounting_setup). JPK_KR wymaga tax_office_id; bez niego podaj tax_office_search (nazwa urzędu), a narzędzie zwróci pasujące urzędy. Niczego nie składa do urzędu.",
        "tags": [
          "Księgi w Systim"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": true,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": true
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "type"
                ],
                "properties": {
                  "company_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID firmy z list_companies. Można pominąć, gdy konto (albo klucz agenta) ma dostęp tylko do jednej firmy."
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "jpk_kr",
                      "balance_sheet",
                      "profit_and_loss"
                    ]
                  },
                  "date_from": {
                    "type": "string",
                    "format": "date",
                    "description": "Od (JPK_KR) (RRRR-MM-DD)"
                  },
                  "date_to": {
                    "type": "string",
                    "format": "date",
                    "description": "Do (JPK_KR) (RRRR-MM-DD)"
                  },
                  "year_id": {
                    "type": "string",
                    "description": "ID roku obrachunkowego (bilans, RZiS)."
                  },
                  "tax_office_id": {
                    "type": "string",
                    "description": "ID urzędu skarbowego w Systim (JPK_KR)."
                  },
                  "tax_office_search": {
                    "type": "string",
                    "maxLength": 80,
                    "description": "Fragment nazwy urzędu, gdy nie znasz jego ID."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/reconcile_sources": {
      "post": {
        "operationId": "reconcile_sources",
        "summary": "Uzgodnij KSeF, panel, Systim i księgę",
        "description": "Raport uzgodnienia faktur firmy w okresie (po dacie wystawienia): rejestr KSeF ↔ dokumenty panelu ↔ rejestry faktur Systim ↔ wpisy księgi ↔ płatności. Dopasowanie po numerze KSeF, potem NIP kontrahenta + numer faktury. Sprawdza nabywcę, walutę, kwoty, daty, duplikaty (także podwójne wpisy w księdze — wpisy zapłat się nie liczą), korekty i zaliczki. Oddziela missing_in_panel (luka panelu) od missing_in_books (faktury nie ma w Systim). Zwraca liczności każdego źródła, okna odczytu, kompletność (complete), listę braków i rozbieżności oraz jawne ograniczenia. Wyłącznie odczyt — nic nie importuje, nie księguje, nie zmienia konfiguracji. Może trwać do minuty. Naprawy: propose_change → zgoda użytkownika → apply_change.",
        "tags": [
          "Uzgodnienie i naprawy"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": true,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": true
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "company_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID firmy z list_companies. Można pominąć, gdy konto (albo klucz agenta) ma dostęp tylko do jednej firmy."
                  },
                  "date_from": {
                    "type": "string",
                    "format": "date",
                    "description": "Data wystawienia od (domyślnie 1 stycznia) (RRRR-MM-DD)"
                  },
                  "date_to": {
                    "type": "string",
                    "format": "date",
                    "description": "Data wystawienia do (domyślnie dziś) (RRRR-MM-DD)"
                  },
                  "include_ledger": {
                    "type": "boolean",
                    "default": true
                  },
                  "include_payments": {
                    "type": "boolean",
                    "default": true
                  },
                  "with_decrees": {
                    "type": "boolean",
                    "default": false,
                    "description": "Czytaj dekret każdego wpisu KH (wolniej)."
                  },
                  "include_matched": {
                    "type": "boolean",
                    "default": false,
                    "description": "Pokaż także pozycje zgodne (domyślnie tylko rozbieżności)."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/propose_change": {
      "post": {
        "operationId": "propose_change",
        "summary": "Zaproponuj zmianę (plan do zatwierdzenia)",
        "description": "Pierwszy krok bezpiecznej naprawy: NIC nie zmienia, tylko zapisuje plan — stan PRZED (panel i, gdy dokument jest w Systim, odczyt z Systim), spodziewany stan PO, źródła, kwoty, daty, ostrzeżenia i blokady (np. faktura już zaksięgowana = podwójny import, ta sama korekta już wystawiona, płatność ponad kwotę). Pokaż plan użytkownikowi i dopiero po jego zgodzie wywołaj apply_change z plan_id. action i args to nazwa i argumenty narzędzia, które wykona zmianę (np. update_document z sale_date). Wysyłka do KSeF nie wchodzi w plan — to zawsze osobny send_to_ksef z osobną zgodą. Plan ważny 24 godziny.",
        "tags": [
          "Uzgodnienie i naprawy"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": true,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": true
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "action",
                  "args"
                ],
                "properties": {
                  "company_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID firmy z list_companies. Można pominąć, gdy konto (albo klucz agenta) ma dostęp tylko do jednej firmy."
                  },
                  "action": {
                    "type": "string",
                    "enum": [
                      "post_document",
                      "update_document",
                      "edit_invoice",
                      "correct_invoice",
                      "unpost_document",
                      "register_payment",
                      "void_document",
                      "refresh_document"
                    ]
                  },
                  "args": {
                    "type": "object",
                    "description": "Argumenty narzędzia z action — w tym document_id."
                  },
                  "reason": {
                    "type": "string",
                    "maxLength": 500,
                    "description": "Po co ta zmiana — np. pozycja z reconcile_sources."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/apply_change": {
      "post": {
        "operationId": "apply_change",
        "summary": "Wykonaj zatwierdzony plan zmiany",
        "description": "Wykonuje DOKŁADNIE plan z propose_change — raz. Wymaga confirmed: true po wyraźnej zgodzie użytkownika na ten plan. Odmawia, gdy dokument zmienił się od propozycji (plan nieaktualny — zaproponuj ponownie), plan wygasł albo ma blokady. Ponowne wywołanie zwraca wynik pierwszego wykonania zamiast powtarzać zmianę. Po zapisie obowiązkowo czyta wynik kontrolnie (panel, a przy dokumencie w Systim — Systim) i porównuje ze stanem spodziewanym. Zapis w księgach klienta.",
        "tags": [
          "Uzgodnienie i naprawy"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": false,
          "destructiveHint": false,
          "idempotentHint": false,
          "openWorldHint": true
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "plan_id",
                  "confirmed"
                ],
                "properties": {
                  "plan_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID planu z propose_change."
                  },
                  "confirmed": {
                    "type": "boolean",
                    "description": "true = użytkownik zatwierdził ten plan."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/list_change_plans": {
      "post": {
        "operationId": "list_change_plans",
        "summary": "Plany zmian i ich wyniki",
        "description": "Plany zmian agentów: zaproponowane, wykonane, nieaktualne — ze stanem przed, spodziewanym po, wynikiem i odczytem kontrolnym. Ślad wszystkich napraw zrobionych przez agentów.",
        "tags": [
          "Uzgodnienie i naprawy"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": true,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": false
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "company_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID firmy z list_companies. Można pominąć, gdy konto (albo klucz agenta) ma dostęp tylko do jednej firmy."
                  },
                  "plan_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Jeden plan."
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "proposed",
                      "applying",
                      "applied",
                      "failed",
                      "stale",
                      "expired",
                      "cancelled"
                    ]
                  },
                  "limit": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 100,
                    "default": 20
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/list_counterparties": {
      "post": {
        "operationId": "list_counterparties",
        "summary": "Kontrahenci",
        "description": "Klienci i dostawcy firmy. search szuka w nazwie i NIP-ie. Zwraca id do faktur.",
        "tags": [
          "Kontrahenci"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": true,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": false
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "company_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID firmy z list_companies. Można pominąć, gdy konto (albo klucz agenta) ma dostęp tylko do jednej firmy."
                  },
                  "search": {
                    "type": "string",
                    "maxLength": 100
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "customer",
                      "supplier",
                      "both"
                    ]
                  },
                  "limit": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 200,
                    "default": 50
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/create_counterparty": {
      "post": {
        "operationId": "create_counterparty",
        "summary": "Dodaj kontrahenta",
        "description": "Dodaje klienta albo dostawcę. Dla firm z Polski najpierw lookup_company_by_nip i przepisz nazwę i adres z rejestru. Zwraca id kontrahenta.",
        "tags": [
          "Kontrahenci"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": false,
          "destructiveHint": false,
          "idempotentHint": false,
          "openWorldHint": false
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "type"
                ],
                "properties": {
                  "company_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID firmy z list_companies. Można pominąć, gdy konto (albo klucz agenta) ma dostęp tylko do jednej firmy."
                  },
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 300
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "customer",
                      "supplier",
                      "both"
                    ]
                  },
                  "vat_id": {
                    "type": "string",
                    "maxLength": 20,
                    "description": "NIP (Polska) albo numer VAT UE z prefiksem kraju."
                  },
                  "country": {
                    "type": "string",
                    "minLength": 2,
                    "maxLength": 2,
                    "description": "Kod kraju ISO, np. PL, DE."
                  },
                  "address": {
                    "type": "string",
                    "maxLength": 200
                  },
                  "postal_code": {
                    "type": "string",
                    "maxLength": 12
                  },
                  "city": {
                    "type": "string",
                    "maxLength": 100
                  },
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "phone": {
                    "type": "string",
                    "maxLength": 40
                  },
                  "bank_account": {
                    "type": "string",
                    "maxLength": 40
                  },
                  "notes": {
                    "type": "string",
                    "maxLength": 1000
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/update_counterparty": {
      "post": {
        "operationId": "update_counterparty",
        "summary": "Zmień kontrahenta",
        "description": "Zmienia dane kontrahenta. Podaj tylko pola do zmiany.",
        "tags": [
          "Kontrahenci"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": false,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": false
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "counterparty_id"
                ],
                "properties": {
                  "counterparty_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID kontrahenta."
                  },
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 300
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "customer",
                      "supplier",
                      "both"
                    ]
                  },
                  "vat_id": {
                    "type": "string",
                    "maxLength": 20
                  },
                  "country": {
                    "type": "string",
                    "minLength": 2,
                    "maxLength": 2
                  },
                  "address": {
                    "type": "string",
                    "maxLength": 200
                  },
                  "postal_code": {
                    "type": "string",
                    "maxLength": 12
                  },
                  "city": {
                    "type": "string",
                    "maxLength": 100
                  },
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "phone": {
                    "type": "string",
                    "maxLength": 40
                  },
                  "bank_account": {
                    "type": "string",
                    "maxLength": 40
                  },
                  "notes": {
                    "type": "string",
                    "maxLength": 1000
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/delete_counterparty": {
      "post": {
        "operationId": "delete_counterparty",
        "summary": "Usuń kontrahenta",
        "description": "Usuwa kontrahenta z panelu (nie z Systim). Kontrahenta z dokumentami nie da się usunąć.",
        "tags": [
          "Kontrahenci"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": false,
          "destructiveHint": true,
          "idempotentHint": false,
          "openWorldHint": false
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "counterparty_id"
                ],
                "properties": {
                  "counterparty_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID kontrahenta."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/get_integrations": {
      "post": {
        "operationId": "get_integrations",
        "summary": "Stan integracji",
        "description": "Systim (konto, weryfikacja), KSeF (środowisko, NIP kontekstu, uprawnienia tokenu, tryb wysyłki) i AI Agent HUB dla firmy. Bez haseł i tokenów.",
        "tags": [
          "Integracje"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": true,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": false
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "company_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID firmy z list_companies. Można pominąć, gdy konto (albo klucz agenta) ma dostęp tylko do jednej firmy."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/connect_systim": {
      "post": {
        "operationId": "connect_systim",
        "summary": "Podłącz program księgowy Systim",
        "description": "Zapisuje i sprawdza dane API Systim firmy (identyfikator konta z adresu <id>.systim.pl, e-mail i hasło API). Hasło jest szyfrowane i nigdy nie wraca. test_only: true tylko sprawdza połączenie. Hasło API podaje użytkownik — nie zgaduj go i nie zapisuj w rozmowie dłużej, niż to konieczne.",
        "tags": [
          "Integracje"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": false,
          "destructiveHint": false,
          "idempotentHint": false,
          "openWorldHint": true
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "systim_id",
                  "systim_email",
                  "systim_api_password"
                ],
                "properties": {
                  "company_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID firmy z list_companies. Można pominąć, gdy konto (albo klucz agenta) ma dostęp tylko do jednej firmy."
                  },
                  "systim_id": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100
                  },
                  "systim_email": {
                    "type": "string",
                    "format": "email"
                  },
                  "systim_api_password": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200
                  },
                  "test_only": {
                    "type": "boolean",
                    "default": false
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/connect_ksef": {
      "post": {
        "operationId": "connect_ksef",
        "summary": "Podłącz KSeF",
        "description": "Zapisuje token KSeF wygenerowany przez użytkownika w Aplikacji Podatnika i sprawdza jego uprawnienia. Token jest szyfrowany i nigdy nie wraca. Środowisko prod = prawdziwe faktury.",
        "tags": [
          "Integracje"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": false,
          "destructiveHint": false,
          "idempotentHint": false,
          "openWorldHint": true
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "token"
                ],
                "properties": {
                  "company_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID firmy z list_companies. Można pominąć, gdy konto (albo klucz agenta) ma dostęp tylko do jednej firmy."
                  },
                  "token": {
                    "type": "string",
                    "minLength": 10,
                    "maxLength": 2000
                  },
                  "environment": {
                    "type": "string",
                    "enum": [
                      "prod",
                      "demo",
                      "test"
                    ],
                    "default": "prod"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/manage_ksef": {
      "post": {
        "operationId": "manage_ksef",
        "summary": "Zarządzaj integracją KSeF",
        "description": "action = verify (sprawdź token i uprawnienia), status, disconnect (usuń token z panelu) albo set_sending (kto wysyła faktury do KSeF: panel, systim, none). set_sending = panel włącza prawne wystawianie faktur z panelu i wymaga confirmed: true po wyraźnej zgodzie użytkownika.",
        "tags": [
          "Integracje"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": false,
          "destructiveHint": true,
          "idempotentHint": false,
          "openWorldHint": true
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "action"
                ],
                "properties": {
                  "company_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "ID firmy z list_companies. Można pominąć, gdy konto (albo klucz agenta) ma dostęp tylko do jednej firmy."
                  },
                  "action": {
                    "type": "string",
                    "enum": [
                      "verify",
                      "status",
                      "disconnect",
                      "set_sending"
                    ]
                  },
                  "sending_via": {
                    "type": "string",
                    "enum": [
                      "panel",
                      "systim",
                      "none"
                    ]
                  },
                  "confirmed": {
                    "type": "boolean"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/get_subscription": {
      "post": {
        "operationId": "get_subscription",
        "summary": "Abonament i zużycie",
        "description": "Plan, stan płatności, data ważności i liczba dokumentów przetworzonych w bieżącym miesiącu (per firma).",
        "tags": [
          "Abonament"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": true,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": false
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/list_billing_invoices": {
      "post": {
        "operationId": "list_billing_invoices",
        "summary": "Faktury za abonament",
        "description": "Faktury VAT wystawione na to konto za abonament Centrum Finansowe.",
        "tags": [
          "Abonament"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": true,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": true
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    },
    "/tools/get_billing_link": {
      "post": {
        "operationId": "get_billing_link",
        "summary": "Link do płatności lub zmiany planu",
        "description": "Zwraca link dla człowieka: portal klienta Stripe (karta, faktury, anulowanie) albo — z plan — stronę zakupu planu Start, Growth lub Scale. Agent nie płaci; płatność kończy użytkownik w przeglądarce.",
        "tags": [
          "Abonament"
        ],
        "x-mcp-annotations": {
          "readOnlyHint": false,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": true
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "plan": {
                    "type": "string",
                    "enum": [
                      "Start",
                      "Growth",
                      "Scale"
                    ]
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wynik narzędzia",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Brak albo nieważny token — WWW-Authenticate wskazuje metadane zasobu"
          },
          "422": {
            "description": "Narzędzie zwróciło błąd (pole error mówi, co poprawić)"
          },
          "429": {
            "description": "Limit 120 wywołań na minutę"
          }
        }
      }
    }
  }
}
