get_budget_status
ChatGPTPer-category budget vs actual for a month, in home currency. Returns paceDay (0–1 fraction of month elapsed), rollup totals, and per-category rows with budgeted/spent/remaining/percentUsed/status. status is computed: 'over' (percentUsed > 1.0, or any spending against a 0.00 budget — overspent by definition), 'warning' (percentUsed > paceDay + 0.10), else 'on-track'. remaining = budgeted + rollover - spent, matching the budgets page exactly (the recurring floor is not subtracted). Foreign-currency transactions still awaiting conversion are excluded from spent and counted in unconvertedCount — when nonzero, disclose that spent figures are temporarily incomplete. Categories with no budget row for this month are NOT returned. month defaults to the current month; format YYYY-MM.
get_budget_status
ChatGPTPer-category budget vs actual for a month, in home currency. Returns paceDay (0–1 fraction of month elapsed), rollup totals, and per-category rows with budgeted/spent/remaining/percentUsed/status. status is computed: 'over' (percentUsed > 1.0, or any spending against a 0.00 budget — overspent by definition), 'warning' (percentUsed > paceDay + 0.10), else 'on-track'. remaining = budgeted + rollover - spent, matching the budgets page exactly (the recurring floor is not subtracted). Foreign-currency transactions still awaiting conversion are excluded from spent and counted in unconvertedCount — when nonzero, disclose that spent figures are temporarily incomplete. Categories with no budget row for this month are NOT returned. month defaults to the current month; format YYYY-MM.
get_cash_flow
ChatGPTCash flow for a period: total income, total spending, net (income − spending), and savings rate. Returns home-currency totals plus per-category breakdowns on both sides. Use this to answer 'did I save anything?', 'what's my savings rate?', or 'where did my money come from?'. Period accepts { from, to } YYYY-MM-DD or { kind } (this_month, last_month, last_30_days, last_6_months, ytd, last_year); defaults to last_30_days. Transfer-category transactions are excluded from both sides. Foreign-currency transactions still awaiting conversion are excluded from both sides and counted in unconvertedCount — when nonzero, disclose that totals are temporarily incomplete. savingsRate is null when income is 0 — disclose to the user rather than reporting 0.
get_cash_flow
ChatGPTCash flow for a period: total income, total spending, net (income − spending), and savings rate. Returns home-currency totals plus per-category breakdowns on both sides. Use this to answer 'did I save anything?', 'what's my savings rate?', or 'where did my money come from?'. Period accepts { from, to } YYYY-MM-DD or { kind } (this_month, last_month, last_30_days, last_6_months, ytd, last_year); defaults to last_30_days. Transfer-category transactions are excluded from both sides. Foreign-currency transactions still awaiting conversion are excluded from both sides and counted in unconvertedCount — when nonzero, disclose that totals are temporarily incomplete. savingsRate is null when income is 0 — disclose to the user rather than reporting 0.
get_financial_accounts
ChatGPTThe user's connected financial accounts (checking, savings, credit cards, brokerages, etc.) with current native AND home-currency balances, native available balance, and a lastSyncedAt freshness signal. Use this to answer 'can I afford X?' or 'how much do I have in Y?' questions. Sum currentBalanceHome across rows for a cross-currency total, but skip rows where currentBalanceHome is null (rate missing — disclose the gap rather than guess). availableBalance is the bank's spendable figure and may be null on accounts like credit cards. Disclose lastSyncedAt when material to the answer; balances are as-of that timestamp.
get_financial_accounts
ChatGPTThe user's connected financial accounts (checking, savings, credit cards, brokerages, etc.) with current native AND home-currency balances, native available balance, and a lastSyncedAt freshness signal. Use this to answer 'can I afford X?' or 'how much do I have in Y?' questions. Sum currentBalanceHome across rows for a cross-currency total, but skip rows where currentBalanceHome is null (rate missing — disclose the gap rather than guess). availableBalance is the bank's spendable figure and may be null on accounts like credit cards. Disclose lastSyncedAt when material to the answer; balances are as-of that timestamp.
get_net_worth
ChatGPTNet worth in home currency: total = assets (checking, savings, brokerage) − liabilities (connected credit cards, loans, mortgages). Balances are SIGNED: liabilities is the signed sum of amounts owed, so a negative liabilities value means net credit (e.g. a refunded card carrying a credit balance) and INCREASES net worth; an overdrawn asset account reduces assets. Returns the current snapshot plus an N-month daily trend series, delta, trendStart (first snapshot date), and trendQuality ('good' | 'sparse' | 'missing'). Use this to answer 'what am I worth?', 'is my net worth growing?', or 'how much have I gained?'. Disclose isPartial (missing exchange rate) AND any trendQuality != 'good' to the user — a sparse snapshot history makes the trend unreliable, and the assistant should say so rather than draw a conclusion from a truncated window. Liabilities cover only connected accounts; manually-tracked debts (mortgages held outside Plaid, IOUs, etc.) are NOT included — caveat the total when it would mislead. connectionsLinkedDuringTrend lists dates within the window when a bank connection was first linked: a step-jump in the trend on one of those dates is a newly-connected account's balance entering the series (onboarding), NOT organic change — do not report it as a gain; attribute it to the new account and, if the user asks 'is my net worth growing?', exclude those jumps from the assessment. trendMonths defaults to 6; set to 0 to skip the trend.
get_net_worth
ChatGPTNet worth in home currency: total = assets (checking, savings, brokerage) − liabilities (connected credit cards, loans, mortgages). Balances are SIGNED: liabilities is the signed sum of amounts owed, so a negative liabilities value means net credit (e.g. a refunded card carrying a credit balance) and INCREASES net worth; an overdrawn asset account reduces assets. Returns the current snapshot plus an N-month daily trend series, delta, trendStart (first snapshot date), and trendQuality ('good' | 'sparse' | 'missing'). Use this to answer 'what am I worth?', 'is my net worth growing?', or 'how much have I gained?'. Disclose isPartial (missing exchange rate) AND any trendQuality != 'good' to the user — a sparse snapshot history makes the trend unreliable, and the assistant should say so rather than draw a conclusion from a truncated window. Liabilities cover only connected accounts; manually-tracked debts (mortgages held outside Plaid, IOUs, etc.) are NOT included — caveat the total when it would mislead. connectionsLinkedDuringTrend lists dates within the window when a bank connection was first linked: a step-jump in the trend on one of those dates is a newly-connected account's balance entering the series (onboarding), NOT organic change — do not report it as a gain; attribute it to the new account and, if the user asks 'is my net worth growing?', exclude those jumps from the assessment. trendMonths defaults to 6; set to 0 to skip the trend.
get_recurring_summary
ChatGPTFull list of the user's recurring rules (subscriptions, monthly bills, yearly payments) with annualized cost + monthly equivalent in home currency. Use this to answer 'what subscriptions am I paying for?' or 'how much do my subs cost per year?'. Each rule includes frequency, native + home amounts, last observed date, and the account it most recently pulled from. Sorted by annualizedCost DESC. status defaults to 'approved' (excludes paused rules); pass 'all' to include paused. frequency defaults to 'any'.
get_recurring_summary
ChatGPTFull list of the user's recurring rules (subscriptions, monthly bills, yearly payments) with annualized cost + monthly equivalent in home currency. Use this to answer 'what subscriptions am I paying for?' or 'how much do my subs cost per year?'. Each rule includes frequency, native + home amounts, last observed date, and the account it most recently pulled from. Sorted by annualizedCost DESC. status defaults to 'approved' (excludes paused rules); pass 'all' to include paused. frequency defaults to 'any'.
get_spending_by_category
ChatGPTTotal spending grouped by category for a given period, returned in the user's home currency. Excludes transfer-category transactions. Foreign-currency transactions still awaiting conversion (no FX rate yet) are excluded from all totals and counted in unconvertedCount — when it is nonzero, disclose to the user that totals are temporarily incomplete. Period accepts either { from, to } YYYY-MM-DD strings or { kind } where kind is one of 'this_month', 'last_month', 'last_30_days', 'last_6_months', 'ytd', 'last_year'. Defaults to last_30_days.
get_spending_by_category
ChatGPTTotal spending grouped by category for a given period, returned in the user's home currency. Excludes transfer-category transactions. Foreign-currency transactions still awaiting conversion (no FX rate yet) are excluded from all totals and counted in unconvertedCount — when it is nonzero, disclose to the user that totals are temporarily incomplete. Period accepts either { from, to } YYYY-MM-DD strings or { kind } where kind is one of 'this_month', 'last_month', 'last_30_days', 'last_6_months', 'ytd', 'last_year'. Defaults to last_30_days.
get_spending_trend
ChatGPTMonthly spending trend in home currency, sorted oldest-to-newest. direction ('up'/'down'/'flat') is robust to single-month spikes: it compares the MEDIAN of the first third vs the MEDIAN of the last third (against a 0.5% tolerance), so a single tax payment or refund won't flip the trend. Trust `direction` over the raw last-vs-first `delta` when they disagree — that's the whole point of computing it this way (issue #40). Returns N months ending at endMonth (defaults to current month). When the window ends at the current PARTIAL month, that month-to-date bucket is excluded from direction/delta/outliers (it is mechanically low, not a real drop) and disclosed in partialMonthExcluded; its entry stays in months as month-to-date data — never read it as a full month. groupBy='category' adds per-category breakdowns per month. delta is the raw last-vs-first difference, surfaced as a secondary signal — use it for the literal start→end change, not for the trend direction. outliers lists months whose modified z-score (median + MAD) exceeds outlierThreshold — a sample-size-aware cutoff (2.0 at n=6, 3.5 at n=12+, interpolated between). The textbook 3.5 cutoff silently drops genuinely anomalous months at small n; the scaled threshold makes a 2x-below-median dip in a 6-month series visible. When outliers is non-empty, disclose them to the user so the headline delta isn't read as a normal run-rate change; when it's empty, you may disclose outlierThreshold so the user knows the screening was performed. Foreign-currency transactions still awaiting conversion are excluded from month totals and counted in unconvertedCount — when nonzero, disclose that totals are temporarily incomplete. Use this to answer 'is my spending going up?', 'what's my monthly trend?', or 'compare this year to last year'.
get_spending_trend
ChatGPTMonthly spending trend in home currency, sorted oldest-to-newest. direction ('up'/'down'/'flat') is robust to single-month spikes: it compares the MEDIAN of the first third vs the MEDIAN of the last third (against a 0.5% tolerance), so a single tax payment or refund won't flip the trend. Trust `direction` over the raw last-vs-first `delta` when they disagree — that's the whole point of computing it this way (issue #40). Returns N months ending at endMonth (defaults to current month). When the window ends at the current PARTIAL month, that month-to-date bucket is excluded from direction/delta/outliers (it is mechanically low, not a real drop) and disclosed in partialMonthExcluded; its entry stays in months as month-to-date data — never read it as a full month. groupBy='category' adds per-category breakdowns per month. delta is the raw last-vs-first difference, surfaced as a secondary signal — use it for the literal start→end change, not for the trend direction. outliers lists months whose modified z-score (median + MAD) exceeds outlierThreshold — a sample-size-aware cutoff (2.0 at n=6, 3.5 at n=12+, interpolated between). The textbook 3.5 cutoff silently drops genuinely anomalous months at small n; the scaled threshold makes a 2x-below-median dip in a 6-month series visible. When outliers is non-empty, disclose them to the user so the headline delta isn't read as a normal run-rate change; when it's empty, you may disclose outlierThreshold so the user knows the screening was performed. Foreign-currency transactions still awaiting conversion are excluded from month totals and counted in unconvertedCount — when nonzero, disclose that totals are temporarily incomplete. Use this to answer 'is my spending going up?', 'what's my monthly trend?', or 'compare this year to last year'.
get_upcoming_recurring
ChatGPTUpcoming recurring charges in the next N days (default 30, max 365). Each item includes the rule id, merchant, category, expected date, expected amount (native + home), the most recent financial account it pulled from, and when it was last observed. Paused rules are excluded; marked-paid periods are advanced.
get_upcoming_recurring
ChatGPTUpcoming recurring charges in the next N days (default 30, max 365). Each item includes the rule id, merchant, category, expected date, expected amount (native + home), the most recent financial account it pulled from, and when it was last observed. Paused rules are excluded; marked-paid periods are advanced.
list_transactions
ChatGPTList the authenticated account's transactions for an optional period and filter set. Returns native + home-currency amounts and excludes transfer-category rows by default. All filter fields are TOP-LEVEL on the input object (no filter wrapper). Filters (all optional, all server-evaluated): merchant is a canonical-merchant substring (case-insensitive ILIKE); categorySlugs restricts to listed slugs; financialAccountIds restricts to listed account public_ids; amountMin/amountMax bound the transaction's home-currency amount (read bb://financial-accounts for homeCurrency) as 2-decimal strings (e.g. "100.00"). When the user's prompt uses a different currency symbol than the home currency, disclose the conversion assumption in the answer. isRecurring matches whether a transaction is part of an approved recurring rule. Paginated; pass cursor from the previous response to get the next page.
list_transactions
ChatGPTList the authenticated account's transactions for an optional period and filter set. Returns native + home-currency amounts and excludes transfer-category rows by default. All filter fields are TOP-LEVEL on the input object (no filter wrapper). Filters (all optional, all server-evaluated): merchant is a canonical-merchant substring (case-insensitive ILIKE); categorySlugs restricts to listed slugs; financialAccountIds restricts to listed account public_ids; amountMin/amountMax bound the transaction's home-currency amount (read bb://financial-accounts for homeCurrency) as 2-decimal strings (e.g. "100.00"). When the user's prompt uses a different currency symbol than the home currency, disclose the conversion assumption in the answer. isRecurring matches whether a transaction is part of an approved recurring rule. Paginated; pass cursor from the previous response to get the next page.
