finerd

Create a complex (split) transaction with multiple FROM and/or TO journals. Use this for splits between several categories or multi-account flows. Each entry in from_journals / to_journals is: {"account_id": str|null, "amount": number, "accrual_month": str|null (optional), "tags": list[str]|null (optional)} Total of FROM amounts must equal total of TO amounts. SINGLE-ASSET, with one exception. Every leg is in the transaction's asset_id; a journal entry has no asset of its own. The exception: one FROM leg and one TO leg carrying different `asset_id`s — buying 18 shares for 1080 CAD, an FX exchange, a points transfer. That is a transfer, and it is booked as one for you; no need to switch tools. That shortcut needs the plain shape — exactly one leg each way, no merchant, no per-leg tags or accrual_month. Anything else with mixed assets (a multi-leg split across currencies) cannot be created in one call: this tool takes a single asset for the whole transaction, and a per-leg asset_id is only accepted by a restructure. Patterns: - Split expense: from = [{account_id: <bank>, amount: 100}], to = [{account_id: <category A>, amount: 60}, {account_id: <category B>, amount: 40}] - Split income: from = [{account_id: <category A>, amount: 700}, {account_id: <category B>, amount: 300}], to = [{account_id: <bank>, amount: 1000}] - Transfer with fee: from = [{account_id: <src>, amount: 1010}], to = [{account_id: <dst>, amount: 1000}, {account_id: null, amount: 10}] - SPREAD ACROSS MONTHS (any of: "розбий цю витрату по місяцях", "rozkydai pidpysku na kvartal", "split this payment over Jan/Feb/Mar", "amortize this annual fee across 12 months", "разнеси по месяцам", "spread this prepayment over 6 months"): from = [{account_id: <bank>, amount: 300}], to = [ {account_id: <Subscriptions>, amount: 100, accrual_month: "2026-01"}, {account_id: <Subscriptions>, amount: 100, accrual_month: "2026-02"}, {account_id: <Subscriptions>, amount: 100, accrual_month: "2026-03"}, ] The cash leaves the bank once but the expense is recognized in three different months. Same trick works on FROM legs for spreading recognized income across months. When `account_id` is null, the server fills in the space's default "Uncategorized Expense" or "Uncategorized Income" account, depending on whether the journal is on the FROM or TO side of a non-money flow. There is no way to leave a journal completely uncategorised — pass an explicit category/account if you need a specific bucket. Per-entry optional fields: - accrual_month: per-leg booking month for accrual reports — the month this leg conceptually belongs to, independent of the transaction date. "YYYY-MM" / "YYYY-MM-01" / "" (clear). - tags: list of tag IDs from search_tags applied to that leg. asset_id is the ISO currency code (e.g. "uah", "usd"). date is optional ISO datetime; server uses now() if omitted. For the merchant pass exactly one of: - merchant_classifier_id: from search_merchants result (preferred) - merchant_account_id: from search_merchants result (use only when merchant_classifier_id is null in the search result)

create_complex_transaction

Create a DEBT account (credit card, mortgage, IOU between people). Direction (required, default "owed_to_me"): - "owed_to_me" — someone owes the USER (friend who borrowed, unpaid invoice from a customer). UI: "Owes me <name>", green. - "i_owe" — the USER owes (credit card, mortgage, loan, friend who lent to user). UI: "I owe <name>", orange. `initial_amount` is the outstanding balance, always a positive magnitude. The MCP flips the stored sign internally based on `direction`. A negative value is rejected. `merchant_classifier_id` links the debt to a business merchant (find via search_merchants — e.g. Chase library merchant id for a credit card). Independent of direction. For human counterparties leave it empty and use `email` / `phone_number` / `link` for contact info. - name: display name (e.g. "Chase Sapphire Reserve", "Andriy IOU"). - asset_id: money currency, lowercase ISO ("usd", "uah", "eur").

create_debt_account

Create a per-space (customer) merchant for a payee that has no global-library entry. A merchant created here carries no balance. Passing merchant_classifier_id links it to a library entry, which brings that entry's logo and mapping with it; without one the merchant stands alone. When the library already holds an entry under the same name and no classifier id was given, the response carries a `library_note` naming it: an unlinked duplicate splits that payee's history, while a name shared by a different business is a legitimate standalone merchant. - name: merchant display name. - merchant_classifier_id: library classifier id, as returned by a merchant search. Required when a library entry for this business exists. - logo_url: a logo image URL (Icon type LINK; per-space, adds NOTHING to the library). It is validated server-side: a dead link or a non-image is dropped and reported in `logo_note`, so a bad URL cannot produce a broken icon. A site's own logo, its favicon or a Wikimedia image works; aggregator endpoints are gated and get dropped. - website: the business's official site URL (stored as debtProperties.link). Per-space only; adds NOTHING to the shared library. A guessed "<brand>" domain often resolves to a parked or for-sale page. A name-only merchant shows a blank placeholder until a logo is supplied. The returned merchant is assignable immediately: its id is the merchant_account_id that transaction tools accept.

create_merchant

Create ONE monthly accrual transaction split across N reward categories. The shape a points-activity CSV's earnings import takes: earnings collapse to one row per (month, item), and those items become the line items of a single monthly transaction — like a receipt. - lines: a list of {"category_id": <REWARD_CATEGORY id>, "amount": <positive points>} objects. Map each CSV earning description to a reward category (list_categories type_filter="REWARD_CATEGORY") and sum identical ones. - asset_id: the reward account's point asset id, verbatim. - kind: "INCOME" for earnings (default) or "EXPENSE". - date: ISO YYYY-MM-DD — use the row's date (last day of the month). - accrual_month: "YYYY-MM" — set to the accrual month for reports. Returns the saved transaction with its split journals.

create_monthly_points_accrual

Create a single-category points earning or expense on a reward account. Records one point movement against one reward category. A whole month of earnings spread across several categories is a different shape and is not what this tool records. - amount: positive point magnitude (sign is conveyed by kind). - asset_id: the reward account's point asset id, verbatim. - reward_category_id: a REWARD_CATEGORY id (from list_categories with type_filter="REWARD_CATEGORY"). - kind: "INCOME" (points earned) or "EXPENSE" (points spent/lost). - date: ISO YYYY-MM-DD booking date. - accrual_month: "YYYY-MM" booking month for reports (optional).

create_reward_pnl_transaction

Record a points redemption — one per booking (e.g. an award hotel stay). Points leave the reward account in exchange for value (the cash-equivalent of what was redeemed). - points_amount / points_asset_id: points spent (positive magnitude). - value_amount / value_asset_id: the cash value of the redemption, in a money currency (asset id lowercase ISO, e.g. "usd"). When it is unknown, a cents-per-point valuation yields an estimate rather than a recorded figure. - value_category_id: EXPENSE category id for the cash-value side (e.g. "Travel", "Lodging", "Hotels"). Find via list_categories with type_filter="EXPENSE". If omitted, the server records it against "Uncategorized Expense". - merchant_id / merchant_classifier_id: where it was redeemed (the hotel) — find via search_merchants. Each redemption usually has its own merchant. - other_account_id / other_amount / other_asset_id: optional cash co-pay leg, for "points + cash" bookings (e.g. 50k pts + $100). - date: ISO YYYY-MM-DD — the real booking date.

create_reward_redemption

Create a loyalty/reward (points or miles) account for a program. A reward account holds a point currency, not money. It must be created from a loyalty-program library merchant — find it with search_merchants and use a result that has reward_asset_ids (e.g. World of Hyatt → "HYT"). - asset_id: the program's point asset id (from reward_asset_ids), verbatim. - merchant_classifier_id: the program's library merchant id (preferred). - initial_amount: opening point balance. With no prior data it is the program's current balance; where history is imported afterwards, a verified balance recorded later is what reconciles the account. A space usually holds at most one account per loyalty program.

create_reward_account

Create a new tag for tagging transactions. Tags are not deduplicated server-side: a near-duplicate of an existing tag is created as a second, separate tag. Tag search matches by PREFIX only, so "no results" is not evidence that a tag does not already exist under another wording.

create_tag

Create a simple expense or income transaction. transaction_type: EXPENSE, INCOME, EXPENSE_REFUND, DEBT_PAY, or DEBT_RECEIVE. amount: positive number. asset_id: ISO currency code (e.g. "usd", "eur", "uah") — lowercase. account_id: bank/cash account ID from list_accounts (optional). category_id: category ID from list_categories (optional; ignored for DEBT_PAY / DEBT_RECEIVE). DEBT_PAY / DEBT_RECEIVE: the counterparty is the MERCHANT — pass the debtor's merchant_account_id (from search_merchants or list_accounts' DEBT account). Without a merchant the call is rejected. date: posting date "YYYY-MM-DD" (optional; defaults to today). The amount is valued in the primary currency at that day's rate. accrual_month: booking month "YYYY-MM" (optional). For the merchant pass exactly one of: - merchant_classifier_id: from search_merchants result (preferred) - merchant_account_id: from search_merchants result (use only when merchant_classifier_id is null in the search result)

create_transaction

Create a NEW transaction from a recognized receipt (bill) and attach the receipt to it. For a bill in list_bills(exclude_assigned=true) that has no matching transaction — a cash purchase, a receipt from an account that is not synced. When a matching transaction already exists (same amount, same day, typically a bank import), this tool produces a duplicate of it; attaching with update_transaction(bill_id=...) is the non-duplicating path, and search_transactions shows whether such a transaction exists. The server builds the transaction from the bill: date and total from the receipt, one expense leg per category found in its items (item↔leg links kept), merchant from the receipt. The money leg is the account the server guesses — the account last used with this merchant, else the wallet — so pass account_id (from list_accounts) whenever the user says where the money came from. The response includes `source_account`, identifying the account used for the transaction. - bill_id: from list_bills / get_bill. Refused if the bill is already on a transaction (the message names it) or has no items (not recognized). - account_id: the money account the receipt was paid from. Replaces the money leg only; the category split stays as recognized. - debt: true books the bill against its merchant as a DEBT counterparty (someone paid for you / you owe them) instead of a money account. Only works when the receipt's merchant is a known person/merchant; with an unknown merchant the server falls back to a money account — check `source_account` in the response. - date: ISO date or datetime, overrides the receipt date; the amount is valued at that day's rate. - comment: optional note.

create_transaction_from_bill

Create a transfer between two of the user's accounts. It records the movement in the finerd ledger only: finerd holds no funds and initiates no payment, so nothing moves at any bank, broker or exchange. Same-asset (the common case): just pass `amount` + `asset_id`; the receiving leg mirrors the sending leg. Cross-asset transfer: also pass `to_amount` + `to_asset_id`. Use this for - BUYING OR SELLING A SECURITY OR CRYPTO — money account out, investment account in, the two legs in different assets and different amounts. "bought 18 shares of EBIT.TO for 1080 CAD" is `account_from=<bank>, amount=1080, asset_id="cad", account_to=<investment>, to_amount=18, to_asset_id="ebit.to_xtse"`. Selling is the same the other way round. This is NOT a complex transaction — that one is single-asset and will reject the two amounts; - point-program transfers between reward accounts (e.g. Bilt → Hyatt: `asset_id="bilt_pts"`, `to_asset_id="hyt_pts"`; usually 1:1 ratio so `to_amount` = `amount`, but some partners have other ratios); - currency-FX between money accounts in different ISO currencies. Each leg is debited/credited in its own asset; the server-side TransferTransactionFactory accepts independent assetIds per leg. account_from / account_to: account IDs from list_accounts. amount, to_amount: positive numbers. asset_id, to_asset_id: asset ids — lowercase ISO for money (e.g. "usd"), program-specific for points (e.g. "hyt_pts", "bilt_pts"); discover via reward_asset_ids on search_merchants or asset_id on get_account_balances. An uppercase code is normalised automatically. date: ISO date or datetime of the transfer, defaults to now. Pass it for anything historical — importing past trades, backfilling. A cross-asset transfer is valued at the rate OF THAT DAY, so a trade booked with the wrong date is also valued at the wrong rate. Passing it here also saves a follow-up update_transaction per row.

create_transfer

Delete a transaction permanently. Get transaction_id from search_transactions or get_transaction. Refused (400) when any leg is bank-posted ("synced": true in get_transaction — SYNCED_TRANSACTION_CANNOT_BE_DELETED): a bank import is the bank's record. Also refused on the partner-owned copy of a family transaction (FAMILY_SYNCED_TRANSACTION_CANNOT_BE_DELETED). A pending (not yet posted) bank row can be deleted.

delete_transaction

List the user's accounts together with their current balances. search: case-insensitive SUBSTRING match on the account name. Archived accounts are not returned. Each account includes amount and currency for each balance entry. Use this when the user asks about balances, totals, or net worth. Pagination: returns up to page_size accounts (default 500, max 1000) plus "has_more". If "has_more" is true, call again with page incremented (page=1, 2, …) and combine the results to cover every account.

get_account_balances

Get Finerd's canonical conversion rate from each asset to a base money currency, on a given date (defaults to today). For reward assets this is the cents-per-point estimate (multiplied by the base unit) Finerd uses internally — e.g. `hyt_pts` → 0.019 means 1 Hyatt point ≈ $0.019 ≈ 1.9 cpp. Use this for the points-import workflow when computing a redemption's `value_amount = points * rate`. Also works for money↔money FX: asset_ids=["uah"], base_asset_id="usd" returns the current UAH→USD rate — use it to convert amounts between currencies (e.g. a budget expressed in one accounting currency into another). - asset_ids: list of asset ids (e.g. ["hyt_pts", "ap_pts"], or money codes like ["uah"]). - base_asset_id: lowercase ISO money asset (default "usd"). - date: ISO YYYY-MM-DD; defaults to today. Returns one entry per asset_id with {asset_id, rate, date}.

get_asset_rates

Balance sheet of a business space: assets, liabilities and equity per account at the end of each period. Business spaces only; a personal space has the net worth report instead. date_from/date_to are ISO dates (YYYY-MM-DD), both optional and defaulting to the last 12 months through today. granularity: MONTH, QUARTER or YEAR. Amounts are in the space's primary currency, which the response names.

get_balance_sheet_report

Get full details for a single bill, including line items. Each item has a name, quantity, unit price, and total price. Get the bill_id from list_bills results.

get_bill

Step 1 of adding a receipt from a file: reserves a bill id (`request_id`) and returns one presigned upload URL per file. The file bytes are then PUT to each `url` with the returned `headers` (raw body, no multipart, no auth) — by whoever holds the file: a shell (curl), a script, an agent runtime with network access. Files pasted into a chat cannot be forwarded here; the upload has to come from an environment that can read the file. URLs are valid until `expires_at` (about an hour). Step 2 is create_bill with the same `request_id`. file_names: 1-10 names with a png, jpg, jpeg, pdf or heic extension, e.g. ["receipt.jpg"]; several pages of one receipt go in one call. Names are returned in `uploads[].file_name` so each file goes to its own url.

get_bill_upload_urls

Get the budget for one month — planned vs actual execution. - month: "YYYY-MM" or "YYYY-MM-DD" (normalized to the 1st of the month). Returns: kind (EXPLICIT = user-set, INHERITED = carried from a prior month, HISTORICAL = a past month with no explicit plan); overall `expense` and `income`, each as {budgeted, effective (after one-off budget events), actual (realized this month)}; and per-category rows (category, budgeted, effective, actual). If no budget is set for that month the result is `{"month": ..., "budget": null}` — that means no budget exists, not a failure. Answers "how am I doing against my budget", and reads the current plan before editing. When a budget exists, the response carries `currency` — the space's primary currency, which every figure here is denominated in; that unit applies to every amount in the response and to no amount outside it.

get_budget

Cash flow report (inflows vs outflows) for a date range. Money that MOVED, both sides of every transfer — not the same thing as the expense/income reports, which count P&L only. Use it for "where did the money come from and go to", debt and investment movements included. date_from/date_to are ISO dates (YYYY-MM-DD). granularity: MONTH, QUARTER, YEAR, CUSTOM, DAY. DAY is the only day-level figure Finerd has, and it answers what people usually mean by "spending per day" / "витрати по днях": how much money left the money accounts each day, `outflow_by_type` split into CATEGORIES / DEBTS / INVESTMENTS, `inflow` likewise, transfers between the user's own accounts excluded. It is cash movement, not the expense (P&L) report — that one books by accrual month and cannot be cut finer than a month, and the two differ when a purchase is booked to another month, an expense is accrued but unpaid, or a debt repayment leaves the account (cash out, not an expense). The response states this in `basis` so the difference can be passed on. Up to ~3 months per call; two calls give a month-over-month day comparison. No `expand`/`include_non_cash` at DAY. Each side is broken down by flow type, and each flow type lists its own categories or accounts under `children`. The five flow types, named after what sat on the other side of the movement: - CATEGORIES — ordinary spending and income - DEBTS — debts, loans and mortgages (borrowing, lending, repayments) - INTERNAL_TRANSFERS — the user's own money accounts: cash, bank, money on the way. Only the leg that left the selected accounts shows up here. - INVESTMENTS — real estate, vehicles, stocks and crypto, electronics, furniture, valuables, other property - OTHER — equity A flow type with no movement in the period is simply absent. expand: one of those five names, to break that one bucket down to its leaf categories as well, e.g. expand="CATEGORIES". This is the fullest of the three levels and the largest response. `by_interval` (per-period totals) appears when the range spans more than one period at the chosen granularity. include_non_cash: movements between income/expense and debt or investment accounts that never touch a money account — accrued loan interest, reinvested income. Counted by default, same as the app. Pass False for "how much money actually moved", which is what a user comparing the report against their bank statement means. This is the app's "Non-cash movements: Show / Hide" filter. The response carries `currency` — the space's primary currency, which every figure here is denominated in; that unit applies to every amount in the response and to no amount outside it.

get_cashflow_report

Aggregated expense report for a date range, grouped by dimension. USE THIS for any question about a period — a month, a week, a few days — because it is the only source of a correct total: it aggregates server-side and converts to one currency. A page of transaction rows is not a total: those rows are per-currency and do not sum to this figure. MONTHLY RESOLUTION: date_from/date_to are ISO dates (YYYY-MM-DD) but the range is WIDENED to whole months — that is the only period this report exists for, and the app's own picker offers months and nothing finer. Ask for 24-31 July and you are answered for the whole of July — the period the response covers can be wider than the one asked for. Day-level figures exist only as cash movement: the cash-flow report at granularity DAY gives per-day outflows from the money accounts (what "spending per day" usually means), which is cash out rather than P&L and is labelled as such. group_by: CATEGORY, MERCHANT, PURPOSE, PARTNER. PURPOSE splits FAMILY (shared family spending) vs PERSONAL; PARTNER splits ME vs PARTNER — WHO PAID in a family, not a business counterparty. Family spending by category or merchant is a query_report question (`family != NOT_FAMILY`, `group category`). Optional filters (all act as INCLUDE allowlists): - category_ids: from list_categories - merchant_ids: merchant_classifier_id or merchant_account_id from search_merchants - tag_ids: from search_tags Returns total spending and breakdown per dimension with prior-period comparison. NOTE: when group_by=CATEGORY the breakdown rolls up to top-level parent categories (e.g. "Food & Essentials" instead of the leaf "Coffee & Snacks"). Leaf-category detail is not in this breakdown; grouping by MERCHANT, or a transaction search filtered to the leaf category, carries it. The response carries `currency` — the space's primary currency, which every figure here is denominated in; that unit applies to every amount in the response and to no amount outside it.

get_expense_report

Aggregated income report for a date range, grouped by dimension. USE THIS for any question about a period — a month, a week, a few days — because it is the only source of a correct total: it aggregates server-side and converts to one currency. A page of transaction rows is not a total: those rows are per-currency and do not sum to this figure. MONTHLY RESOLUTION: date_from/date_to are ISO dates (YYYY-MM-DD) but the range is WIDENED to whole months — that is the only period this report exists for, and the app's own picker offers months and nothing finer. Ask for 24-31 July and you are answered for the whole of July — the period the response covers can be wider than the one asked for. Day-level figures exist only as cash movement: the cash-flow report at granularity DAY gives per-day outflows from the money accounts (what "spending per day" usually means), which is cash out rather than P&L and is labelled as such. group_by: CATEGORY, MERCHANT, PURPOSE, PARTNER. PURPOSE splits FAMILY (shared family spending) vs PERSONAL; PARTNER splits ME vs PARTNER — WHO PAID in a family, not a business counterparty. Family spending by category or merchant is a query_report question (`family != NOT_FAMILY`, `group category`). Optional filters (all act as INCLUDE allowlists): - category_ids: from list_categories - merchant_ids: merchant_classifier_id or merchant_account_id from search_merchants - tag_ids: from search_tags Returns total income and breakdown per dimension with prior-period comparison. NOTE: when group_by=CATEGORY the breakdown rolls up to top-level parent categories. Leaf-category numbers are not in this breakdown; a transaction search filtered to the leaf category carries them. The response carries `currency` — the space's primary currency, which every figure here is denominated in; that unit applies to every amount in the response and to no amount outside it.

get_income_report

Net worth report over time (assets, liabilities, equity). date_from/date_to are ISO dates (YYYY-MM-DD), both optional — omit them for the current net worth and they default to the last 12 months through today. currency: ISO code (e.g., USD, EUR, UAH) — values are converted to this. Omit it and the report is denominated in the space's own primary currency — the same currency the expense, income and cash-flow reports are already denominated in server-side; pass one only when the user asked to see their net worth in a different currency. This response echoes the currency it was answered in; that unit applies to every amount in it. granularity: MONTH, QUARTER, or YEAR (CUSTOM is not supported here). In a business space, where net worth does not exist, the answer is the space's balance sheet (`"report": "BALANCE_SHEET"`, sections → account types → accounts).

get_networth_report

Read one recurring payment by UUID, including amount, currency, frequency and status. Includes next expected date and linked-payment statistics. Expected dates are forecasts.

get_recurrence

Read recurring payment cycles for an inclusive YYYY-MM-DD range of at most one year. Includes past and future cycles for DETECTED and CONFIRMED recurrences. expected_date is a forecast; paid means a linked transaction matched this cycle. paid=false alone does not mean overdue. Amounts retain their own currency.

get_recurrence_calendar

Report this MCP session's capabilities. Returns {role, can_write}. role is MCP_READ (read-only) or MCP_READ_WRITE; can_write is true when write tools (create/update/bulk) are available this session. A read-only session reaches every data tool but has no write tool available to it; write access is chosen when the connector is authorised.

get_session_info

The space's declared primary (base) currency — the currency that reports, net worth and all cross-currency totals are denominated in. Returns {currency, asset_id}, e.g. {"currency": "USD", "asset_id": "usd"}. Useful when an amount's currency is otherwise unlabeled: income/expense reports return bare numbers in this currency. Two spaces can declare different primary currencies, so a figure is only comparable across spaces once both are read.

get_space_primary_currency

Get full details for a single transaction, including journal entries. Journals show the FROM/TO accounts with amounts, currencies, categories, and tags. Use this when you need detailed breakdowns (e.g., split transactions, multi-currency, or per-account amounts). Get the transaction_id from search_transactions results.

get_transaction

Turnover (statement summary) for ONE account over a date range: opening balance, total inflow, total outflow, net movement, closing balance. Use it for "how did account X change between two dates", "what was the balance on date D" (ask for a range ending on D and read `closing`), and for reconciling against a bank statement. It is day-accurate for any dates — unlike the expense/income reports, which only resolve whole months. account_id: exactly one account, as returned by the account listing — the report covers a single account per call. Bank, cash, debt, investment and reward accounts all work; categories are not accounts. date_from/date_to are ISO dates (YYYY-MM-DD), inclusive. asset_id: optional filter to one asset of a multi-currency account, lowercase ("usd", "uah"). `by_asset` has one row per currency the account holds: figures in that currency, plus `*_primary` mirrors converted to the space's primary currency (the `currency` field) when available. `inflow`/`outflow` are gross, `net` is their difference and equals `closing - opening`. `rows_count` is how many transactions moved the account; this report carries the totals only, not the rows themselves.

get_turnover_report

List the user's financial accounts (bank accounts, wallets, etc.). Use search for a case-insensitive SUBSTRING match on the account name. Archived accounts are not returned. Returns account IDs, names, and types. Use the IDs to filter search_transactions by account. Pagination: returns up to page_size accounts (default 500, max 1000) plus "has_more". If "has_more" is true, call again with page incremented (page=1, 2, …) and combine the results to get every account.

list_accounts

List every rate provider available for an asset, their current rate, and which one is selected for this space. Providers: THE_POINTS_GUY, AWARD_WALLET, NERD_WALLET, BANK_RATE, FREQUENT_MILER, ONE_MILE_AT_A_TIME, UPGRADED_POINTS, FINERD_AVERAGE (aggregate), CUSTOM (user-set). The set of valuations that exist for the asset, which is what a change of preferred provider or a custom rate is chosen from.

list_asset_rate_providers

List the user's bills (receipts, invoices). Use date_from/date_to for date ranges (ISO format: YYYY-MM-DD). Use search_string for a case-insensitive SUBSTRING match over the merchant name and the bill's own text: line-item names, address, order id and the whole-number total — so "молоко", an order number or "1234" all find a receipt. Set exclude_assigned=True to show only bills not yet linked to a transaction. Returns bill IDs, dates, amounts, merchants, and line items.

list_bills

List the user's transaction categories. Use type_filter to filter by type: "EXPENSE", "INCOME", or "REWARD_CATEGORY". Reward categories are the dedicated buckets for loyalty points (e.g. base points, bonuses, redemptions) — use them as reward_category_id when creating reward/points transactions. Use search for a case-insensitive SUBSTRING match on the category name as the user named it — often in their own language ("Ресторани", not "restaurant"); omit it to list them all. Archived categories are not returned, so a name missing from a search may still exist archived. Returns category IDs, names, and parent_id when the category is nested under a top-level parent (parent_id absent = top-level). Use the IDs to filter search_transactions; use parent_id to resolve a category's parent and to find same-type top-level parents when creating a new category with create_category. Also includes system_preset for finerd's built-in system categories (e.g. UNCATEGORIZED_EXPENSE / UNCATEGORIZED_INCOME); absent for ordinary categories — use it to spot and exclude system buckets. The same ids are what update_categories takes to rename categories; system categories cannot be renamed.

list_categories

List the banks already connected to this space, with how many accounts each contributed and the connection's sync state. This reflects imported accounts, so it stays empty until the user has finished choosing which accounts to import in the browser — an empty result means the connection is unfinished, not that it failed. One row per connection: the same bank connected twice appears twice.

list_connected_institutions

List the reports this user shared from this space, newest first (at most 50). Each is {id, url, title, public, created_at}: public says whether anyone with the link can open it, or only this user, signed in. Use it to answer "which reports did I share", and to find the report_id of a report shared in another conversation before update_shared_report or unshare_report ("make the September report public", "turn off that link"). Reports that were turned off for good are not listed; links do not expire.

list_shared_reports

List the user's available spaces. Every other tool takes a `space_id`, and these are the ids it accepts. Returns space IDs, names, and whether each is the personal space.

list_spaces

List recorded verified balances for an account (most recent first). Useful to see the last reconciled balance/date for a reward account before re-syncing. Each entry has date, amount, currency, type, correction_amount.

list_verified_balances

Clear the "Needs review" flag on a transaction. Use this when the user says things like "позначити цю транзакцію як переглянуту", "прибери needs review", "mark this as reviewed", "clear the review flag". Pairs with search_transactions(needs_review=True) which lists the transactions currently in the "Needs review" inbox. Get transaction_id from search_transactions or get_transaction. CAVEAT — the flag may not actually clear if the transaction still has unresolved review reasons. The endpoint returns 200 either way (no body), and whether it cleared is readable on the transaction itself: it carries needs_review (present only while still flagged) and needs_review_reason. Each condition below returns 200 and leaves the transaction in the inbox: - Uncategorized journal (reason UNCATEGORIZED): the same save call that flips the flag also re-runs the needs-review processor, which detects the uncategorized leg and re-sets the flag within the same request. Net effect on the inbox: nothing changed. The journal needs a category before the flag can clear. - Old pending journal (>7 days, reason PENDING_TOO_LONG) or pending deleted by the bank (PENDING_TO_DELETED): the server refuses to clear until the user resolves the underlying pending journal (typically by deleting the transaction). - LOADED_OR_IMPORTED (the common "freshly synced" case) clears cleanly and stays cleared.

mark_transaction_reviewed

Custom spending/income reports by exact dates, card, category and other dimensions. query: pipe QL, not SQL. Resolved UUIDs come from account/category/tag tools; merchant takes merchant_account_id, not merchant_classifier_id. APPROVED default. Examples: where type = EXPENSE and counter = <card UUID> and date between 2024-03-01 and 2024-03-31 | group category | sum(primary_amount) as total | sort -total | limit 5000 where type = EXPENSE and direction = TO and date between 2024-03-01 and 2024-03-31 | sum(primary_amount) as total, count_distinct(transaction) as purchases account/category is the own expense category; counter is the paying card. type=EXPENSE with account=<card UUID> is contradictory. parent includes children. Fields: date, accrual, account/category, parent, type, report_type, counter, counter_type, merchant, tag, currency, family, status, direction, tax_deductible, is_synthetic, transaction, amount, primary_amount. Enum values (exact, upper-case) — type/counter_type: BANK_ACCOUNT, CASH, DEBT, REWARD, EXPENSE, INCOME, EQUITY, MONEY_ON_THE_WAY, STOCKS_AND_CRYPTO, LOAN_AND_MORTGAGE, REIMBURSEMENT; report_type: ASSETS, LIABILITIES, EQUITY, PNL; status: PLANNED, DRAFT, APPROVED, REJECTED; direction: FROM, TO; family: FAMILY_I_PAID, FAMILY_OTHER_PAID, NOT_FAMILY (shared family spending = family != NOT_FAMILY; there is no true/SHARED). Filters: AND; = != > >= < <=, in/not in (...), between a and b, is [not] null; tag has ID / has all (IDs); tag not in (ID) includes untagged. Literal values only: account != counter is invalid. No OR, HAVING, field comparisons or arithmetic. Group: field[, field]; date/accrual by day|week|month|quarter|year fill as period. fill needs bounded dates and supplies empty periods. Sort uses existing column aliases (e.g. sort period requires as period). Limit 1..5000, default 500. Aggregates: sum, sum_abs, avg, min, max, count(), count_distinct(field). date is transaction date; accrual is per-leg recognition month (fallback date). Dates YYYY-MM-DD inclusive. Period subtotals use only requested dimensions: category+merchant means group category, merchant, with no date/day dimension. One side (EXPENSE/INCOME) avoids cancellation. Net expenses use signed SUM; refund exclusion requires direction=TO before grouping; refund-only FROM then negate SUM. Net income is negated SUM, not sum_abs. primary_amount is in primary_currency; amount requires currency grouping/filtering. Different currencies and overlapping tag groups cannot be added as an overall total. Facts are split legs, not purchases: average purchase = total/purchases from example 2, undefined at zero. Top purchases: TO, group transaction, SUM, sort -total. Top merchants require merchant is not null before limit. Purchase thresholds apply after transaction grouping. Percent change=(new-old)/old*100, undefined at old=0. Empty SUM/COUNT periods mean zero; grouped queries may return no rows. Sorting does not guarantee qualifying purchases fit within the row limit. truncated=true invalidates a full total even when sorted by amount; complete ranges combine by sum/count, not averages. Per-group distinct counts may overlap. Transfers: money that LEFT an account = direction=FROM, type in (BANK_ACCOUNT,CASH), counter_type in (BANK_ACCOUNT,CASH,MONEY_ON_THE_WAY), group account, sum. Money that ARRIVED = the same with direction=TO. A->B pairs are exact only for manual transfers (counter_type in (BANK_ACCOUNT,CASH)); synced transfers carry counter_type= MONEY_ON_THE_WAY and the other account is not in the facts: report the outflow and say the destination is unknown here. Count transfers as UNIQUE transaction IDs, never rows. Balances/net worth, bank settled/POSTED and receipt items are outside QL. QUERY_INVALID includes a correction reason. Fixed report tools remain available.

query_report

Rename one or more existing categories in one call — for example, translate the whole default set into the user's language. Only the name changes. Nesting, icon and colour stay as they are, and transactions, budgets and reports stay attached to the same category ids. A category shared with a family partner gets the new name for the partner too, as a rename in the app does. This renames the category itself, everywhere it appears. Moving ONE transaction to another category is a different operation — update_transaction with category_id — and leaves every category name as it is. When the category a user names does not exist, the usual fit is an existing category with a similar meaning or a new one from create_category; renaming some other category into that name would relabel all of its transactions. - updates: 1–100 items {"category_id": <id from list_categories>, "name": <new name>}. Names are trimmed, 1–100 characters; an id may appear once. - dry_run: true reads and checks every category and returns the planned `changes` (category_id, old_name → name) without writing anything. A bulk rename is normally shown to the user this way and confirmed before the real call. An id that is not an EXPENSE / INCOME / REWARD_CATEGORY account fails the whole call before anything is written. System categories (system_preset) and archived ones are returned in `skipped` with a reason, names that already match in `unchanged`; neither is written. Returns updated (count), changes, unchanged, skipped, and for a real call failed and not_attempted. Once writing has started the result is always this summary, never an error, so renames that landed are never hidden: a `failed` item carries errorCode, traceId and outcome_unknown (true when the server's answer was lost and the rename may or may not have been applied); `not_attempted` items were not written because the call ran out of time. Repeating the same call is safe: categories already renamed come back in `unchanged`.

update_categories

Search the banks and financial institutions finerd can connect to. Covers bank accounts only. `country_code` ranks that country's institutions first; it does not restrict the results, so a match from another country is a normal outcome; each row carries its own "region". Only root institutions are searchable. A row with "children" is a group of regional branches, all sharing the group's name: the branch is what gets connected, not the group, and the branches differ by "region". A row's "connect_url" is the link to hand to the user; a row without one cannot be connected directly. "connection_started" means a browser connection exists — it flips at the provider handshake, BEFORE any account is imported, and on a group it means merely that one child has one. It is not a signal that the bank is finished — imported accounts are what a connected-institutions listing reports.

search_institutions