Fold

Returns the calling user's Employee Provident Fund (EPF / PF / Employee Provident Fund) snapshot — total balance with per-share split (employee + employer + pension), the most recently declared EPF interest rate and the financial year it applies to, last/next refresh dates, the per-employer service history (joining/exit dates, tenure, masked member id), the per-(employer, financial year) yearly breakdown (opening/closing balances, contributions, withdrawals, interest credited), and an opt-in tail of the 50 most-recent passbook transactions. Inputs: include_employers, include_yearly_breakdown (both bool, default true), include_recent_transactions (bool, default false — opt in when the user asks about specific contributions / withdrawals). Output is always a single snapshot. When the user has NOT connected an EPF account the response carries connected=false and every other field at its zero value (total_balance/shares/rate=0, financial_year empty, refreshed_at/next_refresh_at null, all arrays empty; currency is always "INR") — branch on connected before reading total_balance. No personal details are surfaced (no UAN, name, phone, Aadhaar, PAN, DOB, gender, email, bank account, IFSC, verification timestamps). EPF member IDs are masked to the last 4 characters. Use when the user asks 'what's in my EPF', 'how much PF do I have', 'show my Provident Fund', 'what's the EPF interest rate', 'how long did I work at X', 'how much was credited to EPF last year', or any EPF/PF question. For net-worth aggregates that include EPF alongside other assets, use get_net_worth. Read-only.

Returns mutual fund portfolio insights: market-cap split (large/mid/small/other), asset allocation (equity/debt/other), top sectors, and top securities. Useful for analyzing diversification and concentration.

Returns a one-shot summary of the calling user's mutual fund portfolio: total invested, total current value, gain/loss, gain/loss percentage, holdings count, and a per-asset-category breakdown.

Returns the user's current net worth as a single snapshot — headline total, per-class breakdown across all 12 asset / liability classes, and a liquid / investments / other / debt rollup. Use when the user asks 'what is my net worth', 'how much am I worth', 'what are my total assets', 'what's my total debt', or any cross-asset aggregate. Output: total (assets − liabilities), currency, as_of (latest refresh timestamp across included rows; falls back to snapshot generation time when no included row carries a refresh stamp), assets[] and liabilities[] (each row has class, amount as a positive magnitude, class_enabled, included_accounts, excluded_accounts), and a groups rollup (liquid = bank + cash_on_hand; investments = fixed_deposits + mutual_funds + holdings + nps + epf + ppf; other = manual_assets; debt = credit_card_debt + loans + manual_liabilities; liquid + investments + other − debt = total). Asset classes: bank, fixed_deposits, mutual_funds, holdings, ppf, nps, epf, cash_on_hand, manual_assets. Liability classes: credit_card_debt, loans, manual_liabilities. manual_assets / manual_liabilities are the user's manual instruments (called 'custom entries' in the app) — values they typed in themselves (a flat, a car, gold, money lent out, a loan from family). Each entry is an asset or a liability by the kind the user chose, regardless of its type (a 'Loan'-type entry can be money owed TO the user), and counts current_value × ownership %. Their display_name is the entry's name with its type, e.g. 'Flat in Pune (Property)'. For each entry's full value, ownership share and value history, use list_custom_entries / get_custom_entry. Account inclusion follows the user's net-worth settings — both the class-level toggle (users.net_worth.<class>_enabled; one manual_instruments_enabled toggle covers both manual classes) and the per-account toggle (for bank, credit_card_debt, fixed_deposits, loans, manual_assets, manual_liabilities). Each entry in included_accounts and excluded_accounts carries a server-formatted display_name (e.g. 'HDFC Bank Account ••1234', 'Axis Magnus ••5678', 'ICICI Home Loan ••9999') the AI should echo verbatim, plus issuer / nickname / last_four for custom phrasing. Excluded rows surface with reason 'user_excluded' (user toggled this account off), 'class_disabled' (the whole class is off), or 'parent_excluded' (addon child card following its excluded parent card), so the AI can answer 'why isn't X in my net worth?' and 'what would it be if I re-enabled Y?'. Addon (child) credit cards follow their parent card's toggle as a group: when included they carry included_via_parent (the parent's account_id) and contribute no amount of their own — the parent row carries the whole family's debt. Mutual funds, holdings (stocks), nps, epf, ppf, cash_on_hand have no per-account flag — included_accounts and excluded_accounts are always empty for those classes. Net worth change over time will be a separate tool — this one returns a snapshot only. Read-only.

Returns the user's net worth over a resolved time window — an aggregated daily total series, a per-class start/end change rollup (with per-account include/exclude rosters for the six classes that carry per-account toggles), and an opt-in per-class daily series. Use when the user asks 'how is my net worth trending', 'how much did I grow this year', 'why is my net worth down', 'which class drove the change', or any net-worth-over-time question. Inputs: range ('3m' default, '6m', '1y', or 'custom'), start_date/end_date (YYYY-MM-DD, required only when range='custom'), include_per_class_graph_data (default false). Range '3m' / '6m' / '1y' resolve against today (UTC). The server hard-caps any requested window at ~1 year — a custom range wider than 1 year is REJECTED with a clear error (not silently clamped) so you know to ask for a tighter window. Output: range (the resolved value), start_date / end_date (the resolved bounds), currency ('INR'), summary { start_total, end_total, change_value, change_percent, per_class[] }, graph_data[] (aggregated daily total series, always emitted), per_class_graph_data[] (per-class daily series; ALWAYS emitted as an array — empty when include_per_class_graph_data=false; when true, one row per class in a stable order). summary.change_percent is a fractional ratio (0.12 == 12 %), NOT a 0-100 figure; same for per-class change_percent. ChangePercent is 0 when start is 0 (we never surface infinity/NaN). Per-class rows cover all 12 classes (bank, fixed_deposits, mutual_funds, holdings, ppf, nps, epf, cash_on_hand, manual_assets, credit_card_debt, loans, manual_liabilities). Each row carries class, class_enabled, start, end, change_value, change_percent, included_accounts, excluded_accounts. manual_assets / manual_liabilities are the user's manual instruments (called 'custom entries' in the app) — values they typed in themselves (a flat, a car, gold, money lent out, a loan from family); each entry is an asset or a liability by the kind the user chose, regardless of its type, and its value is current_value × ownership %. Each entry's last recorded value carries forward day by day; get_custom_entry returns one entry's own history points. For liability classes (credit_card_debt, loans, manual_liabilities), start/end and the per-class graph values are reported as POSITIVE magnitudes (the AI sees '₹50k owed' not '-₹50k'). They still SUBTRACT from the aggregated graph_data totals — graph_data is sign-preserving net worth, summary.per_class is sign-flipped for readability. Account inclusion follows the same rules as get_net_worth: the class-level toggle (users.net_worth.<class>_enabled; one manual_instruments_enabled toggle covers both manual classes) AND the per-account toggle for bank / credit_card_debt / fixed_deposits / loans / manual_assets / manual_liabilities. Excluded reasons are 'user_excluded' (per-account toggle off), 'class_disabled' (class flag off), 'pending_connection' (bank account still in first sync), or 'parent_excluded' (addon child card following its excluded parent). Addon (child) credit cards follow their parent card's toggle as a group: when included they carry included_via_parent (the parent's account_id) and contribute no amount of their own — the parent row carries the whole family's debt. The other six classes (mutual_funds, holdings, ppf, nps, epf, cash_on_hand) have no per-account toggle — included_accounts and excluded_accounts are always empty for those classes. For the CURRENT snapshot (today's headline number + breakdown), use get_net_worth — this tool returns history; get_net_worth returns the current state. Read-only.

Returns the calling user's NPS (National Pension System / pension scheme) snapshot — total value across accounts, per-account totals + per-tier rollup (Tier 1 retirement pot + Tier 2 voluntary), and (opt-in) per-scheme list + per-asset-class allocation breakdown. Inputs: include_schemes, include_allocation (both bool, default true; send false to skip an expensive section). Output: connected, total_value (sum of Tier 1 + Tier 2 across all accounts), currency ("INR"), accounts[] (always present — most users have 1 NPS account but the shape supports N). Each account carries masked_pran (masked PRAN — full PRAN is never surfaced), account_status (lowercase "active" or "consent_revoked"), last_fetched_at, total_value, tier_1 / tier_2 (each with current_value, holdings_count, allocation_type lowercase "auto" / "manual" / "" when no tier row), schemes (object with tier_1[] / tier_2[] arrays of {scheme_name, scheme_code, manager_name, asset_class lowercase "equity"/"corporate"/"government"/"alternative", units, nav, current_value, allocation_pct, returns_one_year_pct / returns_five_year_pct nullable; null when include_schemes=false), allocation (object with tier_1[] / tier_2[] arrays of {asset_class, allocation_pct normalised to 100 per tier, current_value, value-weighted returns_one_year_pct / returns_five_year_pct nullable}; null when include_allocation=false). Each tier's allocation always carries 4 rows (equity, corporate, government, alternative) — empty tiers project to 0% across all 4. Performance is NAV-based (no XIRR/CAGR), matching what the iOS app renders. On the not-connected path: connected=false, total_value=0, accounts=[] — branch on connected before iterating accounts. No personal details are surfaced (no PRAN beyond masked, no holder name, DOB, PAN, email, address, mobile, nominee or KYC status). Use when the user asks 'what's in my NPS', 'how much pension do I have', 'show my National Pension System', 'what's my NPS allocation', 'how is my Tier 1 / Tier 2 doing', or any NPS / pension question. For net-worth aggregates that include NPS alongside other assets, use get_net_worth. Read-only.

Returns the calling user's PPF (Public Provident Fund / 15-year tax-saving deposit) snapshot — provider, masked account number, opening and current balance, the PPF interest rate in effect today, account age, maturity date / days-to-maturity, current-FY contributions / withdrawals / interest credited, the lifetime-most-recent contribution and interest-credit dates, and (opt-in) the recent transactions tail. Inputs: include_recent_transactions (bool, default false — opt in when the user asks about specific contributions / withdrawals). Output is always a single snapshot — schema enforces one PPF account per user. When the user has NOT recorded a PPF account the response carries connected=false and every other field at its zero value (balances/rate=0, dates zero, masked_account_number/last_*/balance_updated_at null, provider_name/account_status/current_fy_label empty, recent_transactions=[]; currency is always "INR") — branch on connected before reading current_balance. MaturityDate is opened_on + 15 years. PPF accounts can be extended in 5-year blocks past maturity (the user files a Form H) — extension blocks are NOT modelled in the schema, so AI consumers asking about extensions should treat maturity_date as the FIRST maturity date. account_status is the lowercase wire value: "active" (open) or "archived" (user archived but didn't delete). DELETED rows are never surfaced. masked_account_number is "••" + last 4 (e.g. "••1234") when the user entered an account number; null otherwise. No PAN, DOB, holder name, address or other PII is exposed. Use when the user asks 'what's in my PPF', 'how much have I contributed to PPF this year', 'when does my PPF mature', 'how much PPF interest did I get', 'what's the current PPF rate', or any PPF question. For net-worth aggregates that include PPF alongside other assets, use get_net_worth. Read-only.

Summarise the calling user's spending for one calendar month (or full year, if month is omitted) — the same numbers iOS shows on the home-tab Spending Summary widget. Inputs: month (1-12, optional), year (optional; both default to the current month/year in the user's timezone), include_icon_breakdown (default false). Account inclusion follows the user's spending-summary widget settings; excluded accounts are listed in the response. Each excluded_accounts row carries account_id, account_type, reason, name, last4, is_closed, closed_at and track_from. When explaining an exclusion, say a card or account is CLOSED when is_closed is true (with closed_at) — never describe a closed card only as 'excluded by settings'. Spending before an account's track_from date (see also list_bank_accounts) is untracked by the user's choice, not zero spend; mention the cutoff when it bears on the period asked about. Output: total_amount, categories (each with category_id, category_name, amount, percentage_of_total, transaction_count, and — when include_icon_breakdown=true — an icons[] drill-down), untagged + no_merchant buckets (each with amount, percentage_of_total, transaction_count; null on a zero-spend period), and the included_account_ids / excluded_accounts inventory so the AI can explain which accounts were considered. Percentages are ratios in [0, 1], NOT 0-100. Read-only.

Returns a one-shot summary of the calling user's stocks and ETF portfolio: total current value, ETF value, equity value, total shares, total holdings, and number of demat accounts. Read-only.

Returns the user's total bank balance — the sum of balances across their primary bank accounts. Use when the user asks 'what's my total balance', 'how much money do I have in bank', 'how much across all my accounts', or similar aggregate-bank-balance questions. Output: total (the headline number), currency, as_of (most-recent refresh timestamp among included accounts; null when none included), included_accounts (id, bank_name, balance for each account that contributed), and excluded_accounts (id, bank_name, balance, reason for each excluded account — letting the AI explain 'why isn't X in the total' or 'what would it be if I included Y'). Reason is one of: "user_excluded" (user opted this account out via the app), "passively_tracked" (account is not actively managed and lives in the other-accounts surface), "pending_connection" (first data sync hasn't completed; balance is null). For per-account questions ('what's my HDFC balance'), use list_bank_accounts. For net worth or asset/liability questions, use get_net_worth. For credit card outstanding, use list_credit_cards. Read-only.

Fetch the full detail of one of the calling user's transactions by its id. The row has the same shape list_transactions returns. In particular `amount` is the ORIGINAL figure — not reduced by refunds, and still the full pre-split total on a split parent — while `effective_amount` (COALESCE of remaining_refund_amount, remaining_amount, amount) is the figure that counts towards spending; prefer it whenever the transaction has been refunded or split. `split_type`, `remaining_amount` and `parent_transaction_id` describe this transaction's place in a split, if any. Returns found=false when no such transaction belongs to the user.

Returns the user's connected bank accounts with per-account current balance. One row per account. Fields per row: id, bank_name, nickname (nullable, user-set label), masked_number, holder_name (nullable), account_type (nullable; e.g. SAVINGS, CURRENT), balance (current balance; null while the account is still connecting), currency, is_secondary (true for accounts the user connected via a different phone number — still their own money), is_pending_connection (true while the first data sync hasn't completed; balance is null in that state), tracking ("ACTIVELY" for a primary account; "PASSIVELY" or "PASSIVELY_WITH_TRANSACTIONS" for an account the user keeps but doesn't actively manage), last_refreshed_at, is_closed + closed_at (null when open or unknown), and track_from (YYYY-MM-DD or null). track_from is a data cutoff the user chose: transactions before that date are not tracked anywhere in Fold, so a period before it means no data, NOT zero activity. USE THIS for per-account questions: 'what bank accounts do I have', 'what's my X balance', 'any accounts still connecting', 'when was my Y last refreshed'. DO NOT USE THIS for cross-account aggregations. For 'total balance', 'net worth', 'cashflow', or any sum across accounts, use the dedicated aggregation tools — those apply per-account include/exclude rules that this tool ignores. For credit cards, use list_credit_cards. Read-only.

Lists Fold's category catalog — the tags a transaction can be filed under — with each category's subcategories (called icons in the app) nested underneath. Call it to find the category id to pass to a transaction update. The catalog is GLOBAL: these are Fold's categories, not ones the user created, and there is nothing to create or rename here. No inputs. Output: count and categories[] ({id, name, type[], subcategories[] ({id, name})}), ordered by category name. type lists the transaction directions the category may be applied to — 'INCOMING', 'OUTGOING', or both — and is enforced on write: filing a credit under an OUTGOING-only category is rejected. Category NAMES ARE NOT UNIQUE — 'Return' exists twice, once per direction — so always pass the id, never the name. subcategories is always present and may be empty. Categories the caller's plan does not include are omitted, so every id returned here is one the update path will accept. Read-only.

Lists the user's credit cards with current billing-cycle details: outstanding amount, minimum payment, payment due date, available credit, and whether the previous cycle is paid. Cards may be linked as an addon family (see `relationship`: role PARENT with child_account_ids, or role CHILD with parent_account_id). An addon family shares one statement: the PARENT card's `outstanding` carries the whole family's dues and CHILD cards report 0 — never add a child's cycle totals on top of its parent's. A CHILD card's reconciled cycle `total_amount_due` is the family's combined bill (not child-specific); only its unreconciled `amount_spent_this_cycle` is the child's own spend. Bills are paid on the parent card only. `holder_name` is the cardholder name as the issuer printed it on the parsed statement; null when no name is on record. Closed cards are listed after the open ones with is_closed true and closed_at; their current_cycle, previous_cycle and outstanding are null. They are history only (e.g. to resolve an account_id seen on an older transaction): refer to them as closed and never give bill, due-date or payment guidance for them. Use this for any question about CC bills or due dates. Read-only.

Lists the calling user's custom entries — assets and liabilities they added to Fold by hand because no bank or account feed covers them: a flat or a plot, a car, gold, a stake in a business, crypto, collectables, money lent to a friend, a loan taken from family. No inputs. Each entry carries entry_id, name, type (PROPERTY, VEHICLE, INVESTMENTS, GOLD, RETIREMENT, BUSINESS, CRYPTO, COLLECTABLES, LOANS or OTHER), kind ('ASSET' or 'LIABILITY' — what decides whether it adds to or subtracts from net worth, regardless of type), current_value (the entry's FULL value), ownership_percentage (the user's share, 0-100), counted_value (current_value × ownership_percentage / 100, rounded to 2 decimals — the figure net worth counts), net_worth_enabled (this entry's own net-worth toggle), notes (null when none), document_count (documents attached in the app), opening_date (when the opening value was recorded; null only for old entries with no recorded history), created_at and updated_at (RFC 3339, in the user's timezone). Liabilities are stored as POSITIVE amounts — a ₹5L loan taken shows current_value 500000 with kind 'LIABILITY' — and are subtracted only when net worth is computed. The class-wide on/off switch for custom entries and their totals (manual_assets / manual_liabilities) live in get_net_worth and get_net_worth_history; an entry with net_worth_enabled=true still does not count when that class switch is off. For one entry's value history, use get_custom_entry. Ordered assets first, then by type, newest first. Read-only.

Lists the user's fixed deposits with a roll-up summary header (count, total principal, total maturity, total interest on maturity, principal-weighted average interest rate). One row per FD, sorted by maturity date (soonest first). Inputs: status ('active' default, 'archived', or 'all' — case-insensitive; DELETED rows are never returned), limit (1-200, default 100). Per-FD fields: account_id, institution_name, nickname (nullable, user-set label), masked_account_number (nullable), display_name (server-formatted human label like 'HDFC Bank Salary FD ••1234' the AI can echo verbatim), principal_amount, maturity_amount, interest_rate (annual %), interest_on_maturity, opening_date / maturity_date (YYYY-MM-DD), tenure (years/months/days), days_to_maturity (signed; negative when already matured), status ('active' or 'archived'), is_matured, auto_renews, account_type (lowercase, e.g. 'fixed' / 'recurring' / 'sweep'), interest_payout (nullable, lowercase), interest_computation (lowercase). The summary header aggregates the SAME row set returned in the body, so the totals always match the inventory. USE THIS for any FD question: 'what FDs do I have', 'when do my FDs mature', 'what's my total FD principal', 'do I have any archived FDs', 'how much interest will I earn from my FDs'. For net worth that rolls FDs in alongside other assets and honours per-account widget toggles, use get_net_worth. Personal/holder details (name, DOB, PAN, email, mobile, KYC status, IFSC, branch) are deliberately omitted. Read-only.

Lists the calling user's transaction groups — user-created collections of transactions (e.g. a trip, a home renovation, shared flat expenses) used to track project or shared spending. Input (optional): status ('ACTIVE' default, or 'ARCHIVED'; case-insensitive). Each row carries id, name, status, is_pinned, incoming_count / incoming_amount (credits), outgoing_count / outgoing_amount (debits), created_at, and transactions_updated_at (the group's latest-activity timestamp — the same value the app sorts the groups list by; rows are returned in that order, most recent first). The rollups are user-scoped: only transactions on accounts the user can see count, hidden transactions are excluded, and cash-flow-excluded transactions follow the group's own include-in-totals preference — the numbers match what the user sees in the Fold app. Response: groups[] and count (== len(groups)). To see what is inside a group, pass its id to list_transactions as group_ids. Read-only.

Lists the calling user's mutual fund holdings, one row per scheme (ISIN), with units, invested amount, current value, gain/loss, asset category, plan name, and risk profile. Supports an optional case-insensitive asset_category filter and a limit (1-100, default 100).

Lists the user's mutual fund transactions (buys/sells), with optional filtering by type and free-text search. Cursor-based pagination: the first call omits cursor; subsequent calls pass the next_cursor value from the previous response. next_cursor is nil when there are no more pages.

Lists the calling user's recurring expenses (subscriptions, bills, EMIs), sorted by upcoming due date. Filter by status (ACTIVE/ARCHIVED/STOPPED; default ACTIVE). Cursor-based pagination. Read-only.

Lists the calling user's refund groups — user-created links between one or more spends and the refunds / returns / reversals that offset them (a returned order, a cancelled booking, a reimbursed expense). One row per group, most recently updated first. Distinct from list_groups, which returns the user's transaction groups. Inputs: statuses (optional; any of 'ACTIVE', 'SETTLED', 'SURPLUS', case-insensitive; omit for all three). Per-group fields: id, name, status, net_amount, left_to_settle, transaction_count. net_amount is the stored settlement figure — the sum of the group's credits MINUS the sum of its debits — so it is NEGATIVE while part of a spend is still un-refunded, 0 once refunds exactly cover the spends, and positive when refunds exceeded them. status is derived from that sign: 'ACTIVE' (net_amount < 0, a refund is still outstanding), 'SETTLED' (0), 'SURPLUS' (> 0, refunded more than was spent). left_to_settle is max(0, -net_amount) — the un-refunded remainder as a POSITIVE figure, and 0 for SETTLED and SURPLUS groups. Quote left_to_settle when the user asks how much is still to come back; quote net_amount only when a signed figure is wanted. transaction_count counts only transactions the user can still see — hidden transactions, and transactions on deleted or passively-tracked accounts, are not counted — so it can legitimately read 0 for a group that still exists. A transaction belongs to at most one refund group, and a group holds at most 200 transactions. Groups saved WITHOUT a name are not returned: treat this as the user's named refund groups, not an exhaustive account of every refund link they have made. Linking a refund rewrites how the member transactions count towards spending: each spend carries its un-refunded remainder, and the refund credits consumed offsetting those spends are excluded from cash flow so they do not read as income. get_spending_summary and compare_spending_periods already apply that netting, so a fully refunded spend contributes 0 to spending totals there and needs no adjustment by you. To see what is inside a group, pass its id to list_transactions as refund_group_ids — that returns both the spends and the refunds, each row carrying its own remaining_refund_amount. USE THIS when the user asks 'what am I still waiting on a refund for', 'how much is yet to be refunded', 'which refunds have come through', or any refund / return / reimbursement question. Read-only.

Lists the calling user's stocks and ETF holdings, merged by ISIN, sorted by current value descending. Supports a limit (1-100, default 100). Read-only.

Lists the user's stocks and ETF transactions (buys, sells, bonuses, splits, dividends, rights, others), most recent first. Optional filters: type, holding_id. Cursor-based pagination — pass next_cursor from a prior call to fetch the following page. Read-only.

List the calling user's own financial transactions. Filters (all optional): limit (1-100, default 25), cursor (opaque pagination token from next_cursor), type ('debit' or 'credit'), start_date / end_date (YYYY-MM-DD, inclusive / exclusive), exclude_non_cashflow (hide transfers / loan repayments / internal moves), bookmarked_only (only the transactions the user has bookmarked), sort_by ('date' default, or 'amount'), sort_order ('desc' default, or 'asc'), account_ids (one or more bank/credit-card account UUIDs), sources ('bank', 'credit_card', and/or 'manual'), category_ids / subcategory_ids (UUIDs), refund_group_ids (UUIDs from list_refund_groups — returns exactly the transactions linked to those refund groups, both the spends and the refunds that offset them), and group_ids (UUIDs from list_groups — returns the transactions the user has filed into those transaction groups). For both group filters an unknown id is not an error, it simply matches nothing. Sort dimensions MUST stay constant across pages of the same cursor walk — the cursor pins a value of the sort column, so changing sort_by/sort_order between pages would silently skip / re-emit rows. Each row carries two timestamps: `date` is when the transaction actually happened (bank-reported time, used for ordering and the date-range filter); `account_in` is a USER-CONTROLLED override that moves the transaction into a different calendar month for cash-flow / spending-summary accounting — for example, a salary credited Jan 31 can be moved into February so it counts under Feb's cash flow. `account_in` is null when the user hasn't moved the transaction; when present, it overrides `date` for monthly accounting only (not for ordering or the date-range filter). The get_spending_summary tool already applies COALESCE(account_in, date) server-side. Each row also carries `account_id` (the bank/credit-card/manual account this transaction belongs to — join key for list_bank_accounts / list_credit_cards results), a nested `category` envelope (null when the transaction is uncategorised; otherwise {id, name, subcategory} where the inner subcategory ({id, name}) is null when the user has not picked an icon under the category), `excluded_from_cash_flow` (true when the transaction is hidden from cash-flow / spending totals — transfers, loan repayments, internal moves, or user-marked exclusions; the same flag that the `exclude_non_cashflow` input filters on), and `is_bookmarked` (true when the user has bookmarked the transaction; the flag `bookmarked_only` filters on). Two refund fields complete each row: `refund_group_id` (the refund group this transaction is linked to, or null — a transaction is in at most one; resolve the name via list_refund_groups) and `remaining_refund_amount` (the un-refunded remainder of a spend a refund group has offset: 0 when refunds covered it entirely, the shortfall when they covered part, null when refund netting has not touched this row). `group_ids` lists the transaction groups this transaction has been filed into — an array (a transaction can be in several), empty when it is in none; resolve names via list_groups. Three split fields complete each row. A user can SPLIT a spend — carving child transactions out of it, each taking its own category, merchant and notes, while the original row keeps the leftover. `split_type` is 'PARENT' on that original row, 'CHILD' on a carved-off piece, and null when splitting never touched the transaction. `remaining_amount` is the parent's own leftover, the part still carrying the parent's category and notes (null on children and on non-split rows). `parent_transaction_id` points a child back at its parent (null otherwise) and is the only reliable way to group a split back together. This tool returns a parent and its children as SEPARATE sibling rows. `amount` is always the ORIGINAL figure in both directions: it is NOT reduced by refunds, and on a split PARENT it is still the full pre-split total even though that transaction's children are returned as their own rows alongside it. Use `effective_amount` for anything you sum — it is COALESCE(remaining_refund_amount, remaining_amount, amount), the exact figure the spending engines resolve, and the only field that reconciles with get_spending_summary. Summing `amount` instead overstates refunded spend and double-counts every split. Response: transactions[] (this page), count (this page's size, == len(transactions)), total_matched (count across ALL pages of the filter — populated only when truncation was detected; on the non-truncated path it is 0 and count IS the true total), and next_cursor (opaque pagination token; null when there are no more pages). Returns only transactions the user can already see in the Fold app. Without account_ids, bank transactions come only from actively tracked accounts (the app's main feed). A bank account that list_bank_accounts reports with tracking 'PASSIVELY_WITH_TRANSACTIONS' is left out of that feed — pass its id in account_ids to read its transactions. Accounts with tracking 'PASSIVELY' (balance only) have no transactions here. A bank account with a `track_from` cutoff (see list_bank_accounts) has no transactions before that date anywhere in Fold — the user chose not to track that period, so treat it as untracked, never as zero spend. For manual transactions (source 'manual'), account_id is the user's Cash on hand; filter them with sources=['manual'] rather than account_ids. Read-only.

Lists individual recurring-expense cycle instances (single payments) within a date range, sorted by due date. Includes UPCOMING/OVERDUE/PAID statuses and projects future cycles for dates beyond the backfill window. Default range: today to today + 30 days. Read-only.

Merges a split CHILD transaction back into its parent, undoing one split_transaction call. WRITES to the user's data, so confirm with the user before calling unless they have clearly already asked for this. Input: transaction_id (required) — the UUID of the CHILD leg to merge back, a transaction whose `split_type` is "CHILD". Passing the PARENT's id, or any transaction that is not a split child, is rejected. This DELETES the child transaction and everything that was ever added to it — its notes, its receipts, its own category and merchant. That is NOT recoverable: splitting again creates a fresh child, it does not bring the old one back. What returns to the parent is only the amount. The parent itself, and the original spend, are untouched. Merging the LAST remaining child resets the parent entirely: its `split_type` and `remaining_amount` go back to null and it stops being a split at all. The parent view returned shows whichever of those two states applies, so read it rather than assuming. Refused when the PARENT has since been linked to something that assumes a fixed amount — a recurring-expense cycle, a credit-card bill, or a refund group — because handing the amount back would contradict that link. Not idempotent in the way that matters: once the child is gone, calling again with the same id fails with 'transaction not found'. Never retry blindly on an unclear result — re-read with get_transaction first. Output: parent (the parent as it now stands, same shape as list_transactions) and merged_amount (the amount handed back to it). parent is null only when the merge succeeded but reading the parent back afterwards failed — treat that as a failed READ, not a failed merge.

Splits one of the calling user's transactions by carving a piece off it — the same split the Fold app offers on a transaction. WRITES to the user's data, so confirm with the user before calling unless they have clearly already asked for this exact split. This is CARVE-OFF, NOT divide-into-N. One call creates ONE child transaction of the amount you name and the parent keeps whatever is left in its `remaining_amount`. There is no 'split into 3 equal parts' operation and the amounts you pass do not have to sum to anything: to split a 900 lunch three ways, call this TWICE for 300 each, and the 300 still sitting on the parent IS the third piece. Inputs: transaction_id (required — the PARENT's UUID, from list_transactions or get_transaction), amount (required), and optionally category_id / subcategory_id from list_categories to file the child under. OMIT category_id to let the child inherit the parent's category; pass an EMPTY STRING to leave the child uncategorised instead, the same way an empty string clears a field on update_transaction. amount must be at least 0.01 and STRICTLY LESS than what the parent has left: its `remaining_amount` once it has been split at least once, otherwise its `amount`. A parent always keeps a positive remainder, so a split that would consume the whole transaction is rejected — read the parent with get_transaction first when you are not sure what is left. A parent may carry at most 20 children. NOT IDEMPOTENT: calling twice carves TWO children, not one. If a call comes back unclear — a timeout, an error you cannot read — do NOT retry it. Call get_transaction on the parent and look at `remaining_amount` and the child rows to see whether the split already landed. There is deliberately NO merchant input and NO notes input here. The child INHERITS the parent's merchant, and notes are NEVER inherited (a note written about the whole transaction does not describe the slice). To give the child its own merchant or its own note, call update_transaction on the child_transaction_id this returns. The child inherits everything else too — the account, the date, the cash-flow flag, the receipts, and the parent's category unless category_id is given — and it joins EVERY transaction group the parent is in, so a group's total still covers the whole of what was spent. These transactions CANNOT be split and the call is rejected with the reason: manual transactions (entered by hand rather than fetched from a bank), a transaction that is itself a split CHILD (splits do not nest), credit-card bill payments and transactions linked to a credit-card bill, hidden transactions, transactions inside a refund group, and transactions linked to a recurring-expense cycle. Output: child_transaction_id (the new child's UUID — pass it to update_transaction to tag it further), child, and parent (both in the same shape list_transactions returns; the parent as it NOW stands, with split_type "PARENT" and a reduced remaining_amount). child and parent are null only in the rare case where the split succeeded but reading the rows back afterwards failed — child_transaction_id is still the id that was created, so treat a null view as a failed READ and never as a failed split. To undo a split, call merge_split on the child.

Changes one of the calling user's custom entries (user-added assets and liabilities — see list_custom_entries). WRITES to the user's data — the change is what they will see in the Fold app, so confirm with the user before calling unless they have clearly already asked for this exact change. Inputs: entry_id (required) plus any of name, type, current_value, ownership_percentage, notes and opening_date; at least one is required and an omitted field is left untouched. notes="" clears the note. current_value stays a positive amount for a liability. A change to current_value, ownership_percentage or type records a NEW history point dated today (the moment of the call), so it says 'the value is now X' — it cannot backdate a value. Sending the value the entry already has records nothing. opening_date moves only the OPENING value's date (the first history point) and must be strictly before the entry's created_at; it accepts the same formats as on create_custom_entry. A few old entries have no recorded opening value (opening_date null) and their opening_date cannot be set. kind cannot be changed: to turn an asset into a liability or back, delete the entry and create it again. The net-worth toggle and attached documents are managed in the Fold app, not here. Output: entry (as it now stands, same shape as list_custom_entries) and previous — for each field you sent, its value BEFORE this call, in this tool's own input shape (fields you did not send are null; notes is "" when there was none). Passing previous back undoes the change, but history is not erased: undoing a value change adds ANOTHER history point dated today rather than removing the one this call added. Restoring a previous opening_date normally works too; in the rare case it is refused for not being strictly before created_at, tell the user and leave the opening date as it is.

Re-tags the calling user's own transactions: notes, category, subcategory, merchant, whether they count towards cash flow, which month they are accounted in, and whether they are bookmarked. WRITES to the user's data — the change is what they will see in the Fold app, so confirm with the user before calling unless they have clearly already asked for this exact change. Inputs: transaction_ids (required, 1-25 UUIDs from list_transactions, all the caller's own) plus any of notes, category_id, subcategory_id, merchant_name, remove_merchant, excluded_from_cash_flow, account_in, is_bookmarked. At least one of those eight is required, and every one given is applied to EVERY listed transaction — so batch only transactions that should all end up the same. Clearing vs leaving alone: an omitted field is left untouched, an empty string CLEARS it (notes, category_id, account_in). remove_merchant unsets the merchant and cannot be combined with merchant_name. excluded_from_cash_flow takes the transactions out of (true) or back into (false) cash-flow and spending totals — the same toggle as the app. It is refused, and the whole call fails, for a bank transaction linked to a credit-card bill or a credit inside a refund group, because their exclusion is already derived. Setting a category can also change this flag on its own: filing a transaction as a self-transfer excludes it, moving it off self-transfer includes it again. account_in moves transactions into another calendar MONTH for cash-flow and spending-summary accounting without changing when they happened — a salary credited Jan 31 accounted into February, say. Pass a date as YYYY-MM-DD (read in the user's timezone) or an RFC 3339 timestamp; only the month it lands in matters. It may move a transaction ONE month either way at most — into the month before or the month after the one it happened in — and a date further out is refused, failing the whole call. A date inside a transaction's own month clears that transaction's override rather than duplicating it, and an empty string clears it outright. is_bookmarked bookmarks (true) or un-bookmarks (false) the transactions, the same toggle as the app. category_id / subcategory_id come from list_categories. A category only accepts transactions in a direction its `type` lists, so an INCOMING transaction cannot be filed under an OUTGOING-only category. There are two ways to set the merchant, and they cannot be combined. merchant_name is free text, matched EXACTLY (case-insensitively) against the user's own merchants and Fold's catalogs; when nothing matches, a new custom merchant is CREATED with that name and appears in the user's merchant picker from then on — a real side effect beyond these transactions, so prefer the plain canonical name ("Swiggy", not "Swiggy order 4th Aug") and tell the user when merchant_resolution.outcome is "created". merchant_id + merchant_type instead names a SPECIFIC merchant from find_merchant_to_tag — use that pair when the name is ambiguous, when a particular outlet is meant, or when you want Fold's catalog brand rather than whatever an exact name match happens to hit. Pass both back exactly as that tool returned them. Output: updated_count, transactions[] (the rows as they now stand, same shape as list_transactions), previous[] ({id, category_id, subcategory_id, notes, merchant_id, merchant_type, excluded_from_cash_flow, account_in, is_bookmarked} as they were BEFORE this call — pass these back to undo it), and merchant_resolution ({outcome, id, name, type}, null when merchant_name was not given). The whole call fails if any transaction id is not the caller's, so a partial update never happens silently. Some tag rules are applied server-side and may change more than was asked: filing a transaction as a self-transfer also sets its merchant to "Myself", and moving it off self-transfer clears that merchant again. Read `transactions` in the response rather than assuming the patch applied verbatim.