Finanse.app

THE tool for a shop receipt — a paragon, a till or cash-register slip, a photographed or scanned bill, an itemised order. Use it for ANY request to add, split, categorise or book a receipt ("podziel ten rachunek na kategorie i dodaj do wydatków", "add this receipt split by category"), including when you have already read every line off the photo and worked out the split yourself — that is exactly the input this tool wants. Never book receipt lines with create_transaction or create_transactions instead: only this tool reconciles against the printed total, shows the user the split before anything is written, and collapses the lines into one transaction per category. Send EVERY line as a separate item with its own name and amount; send discount or rabat lines as NEGATIVE amounts. Items are then summed per category and stored as one transaction per category, so a 45-line receipt becomes a handful of rows. purchasedAt is REQUIRED and is the date AND time PRINTED ON THE RECEIPT as a plain wall clock, "2026-09-17T17:20" — never append Z and never convert it yourself. Read the time off the receipt: on a Polish paragon fiskalny it is printed next to the date in the footer (e.g. "2026-09-26 09:39" beside the print number), and again on the card-payment slip. A date without the time, or no purchasedAt at all, is rejected — never substitute noon or the current time; pass the shopper's IANA timeZone separately when you know it. total is the printed SUMA and is only used to reconcile. Leave categoryId null on any item you are unsure about — the server fills it in from this project's own history, which is more reliable than guessing. Before categorizing, call list_categories to fetch this project's expense categories. Explicit user/model assignments take priority over history. Corrections must resend the COMPLETE corrected receipt and produce a fresh preview; never reuse an earlier token after corrections. Approval may come from the widget or chat: chat approval must use the most recent reviewed token. Unassigned items and non-positive category totals prevent confirmation until corrected. Requires an active subscription. Two-step and server-enforced: call first WITHOUT confirmationToken and nothing is written — you get the per-category breakdown and a short-lived confirmationToken. Show that breakdown, wait for the user's explicit approval, then call again with that exact token. IMPORTANT: if this returns status "preview", say you prepared the breakdown — do NOT say it was blocked or failed, and never claim the expenses were added until status is "saved".

create_receipt_expenses

Moves money toward a savings goal by changing how much it holds. amount is added, and a negative amount withdraws. This only tracks the goal — it records no transaction and moves nothing between accounts. Requires an active subscription.

allocate_funds

Update several existing transactions at once — recategorise, append notes, or correct amounts/dates across many rows in one call. Pass EVERY change via updates — never call this once per transaction, or the user gets one confirmation card per row instead of one for the batch. The account balance and each category's occurrence count are recalculated together, atomically. Requires an active subscription. Two-step and server-enforced: call first WITHOUT confirmationToken and nothing is written — you get back the current and resulting rows plus a short-lived confirmationToken. The preview renders as a card with Confirm and Cancel buttons: do not re-list it, ask for approval in one short sentence. The confirmation binds the whole batch, so if the user approves in chat the second call takes no arguments but that exact token. IMPORTANT: if this tool returns status "preview", tell the user you prepared the preview. Do NOT say the operation was blocked or failed.

bulk_update_transactions

Create a recurring payment rule (a subscription, rent or other repeating bill), typically one the user picked from show_recurring_suggestions. Only call it after the user has explicitly asked to automate that payment. Renders nothing — confirm in one short sentence once status is "saved". The rule starts today and repeats every intervalCount intervalUnit (e.g. 1 month). With autoAdd true the app books each occurrence as a transaction on its due date, starting today; with autoAdd false it only reminds the user. amount is a positive number; the direction (expense or income) follows the category from list_categories. accountId defaults to the project default account. The rule can be edited or removed later in the Finanse app. Requires an active subscription.

create_recurring_transaction

Record several unrelated expenses or incomes the user already made, in one call — never call create_transaction once per row when you already know the whole set. NOT for a shop receipt: one paragon, till slip, photographed or scanned bill or itemised order split across categories is create_receipt_expenses, which reconciles against the printed total and has the user approve the split first; reach for it even when you have already read the lines and worked out the split yourself. Each item works like create_transaction: the direction follows its categoryId, date is the wall clock exactly as a person reads it ("2026-09-17T17:20", never append Z) — always include the time when you know it (a date alone is booked at 12:00), and accountId defaults to the project default account. Requires an active subscription. The saved rows render as one card — it is the confirmation: do not re-list them, at most one short sentence. IMPORTANT: the transactions are stored ONLY if this tool returns status "saved". If you get an error, no result, or the turn is interrupted before that arrives, nothing was recorded — say so and retry. Never tell the user they were added without that confirmation.

create_transactions

Record ONE expense or income the user already made, from a single amount they state. NOT for a shop receipt: a paragon, till slip, photographed or scanned bill or itemised order goes to create_receipt_expenses even when you have already read its lines and worked out the split yourself. amount is a positive number. The direction (expense or income) is taken from the chosen category, so pick the right categoryId from list_categories. date is the wall clock exactly as a person reads it ("2026-09-17T17:20") — never append Z and never convert it yourself; pass the IANA timeZone separately when you know it, otherwise Warsaw is assumed. Always include the time when you know it; a date alone is booked at 12:00. It defaults to now. accountId defaults to the project default account. Requires an active subscription. Call list_accounts first only when the user names an account. The saved transaction renders as a card — it is the confirmation: do not repeat its amount, category, account or date, and do not draw your own summary; at most one short sentence. IMPORTANT: the transaction is stored ONLY if this tool returns status "saved". If you get an error, no result, or the turn is interrupted before that arrives, nothing was recorded — say so and retry. Never tell the user it was added without that confirmation.

create_transaction

Permanently delete one or more transactions and revert their effect on the account balance. This cannot be undone. Pass EVERY id you intend to remove in a single call via transactionIds — never call this once per transaction, or the user gets one confirmation card per row instead of one for the batch. Requires an active subscription. Two-step and server-enforced. Call it first WITHOUT `confirmationToken` — nothing is modified and you get back the real stored transaction, the resulting state and a short-lived `confirmationToken`. The preview renders as a card with Confirm and Cancel buttons: do not re-list it, ask for approval in one short sentence. If the user approves in chat instead of on the card, call again with the identical arguments plus that exact token. The token cannot be guessed or reused for different arguments, so a call without it never writes. IMPORTANT: if this tool returns status "preview", tell the user you prepared the preview. Do NOT say the operation was blocked or failed.

delete_transaction

Silent, filtered transaction lookup for your own reasoning — renders nothing. Use it for every task that needs rows as data: recategorising, ids to update or delete, duplicates, counting, totals for a merchant, checking which rows match a rule. Filters combine with AND; queries match notes (any term). Dates are calendar days in the project's time zone, inclusive. At most 500 rows, newest first; truncated=true means narrow the filters or split the range. Never follow it with show_transactions or show_search_results unless the user asks to see the rows.

find_transactions

Life events the household marked in the app — a move, a new job, a birth, a death in the family, a job loss. Read-only context for explaining why spending or income changed; never ask the user to describe these, and never add them (the user enters them in the app). An event with endDate null is a one-off change that still applies from startDate on. Dates are YYYY-MM-DD, inclusive; omit both to get every event.

list_life_events

Silent lookup, renders nothing. The project's accounts (id, name, balance, isDefault) plus today's date and time zone. Call it before a write only when the user names an account ("z konta Alior") or a relative date needs today; otherwise writes use the default account. transfersOnly accounts (savings, emergency fund) never take expenses or incomes. Use show_project_overview only when the user asks to SEE their accounts.

list_accounts