Era Context

Tools 57

• Accounts List Financial Accounts

  List all linked bank accounts, credit cards, and investment accounts with current and available balances. Use this when the user asks about their accounts, which banks they use, or when you need an account_group_key to pass to other tools like accounts__check_account_balance or transactions__list_transactions. When a result — or a section of it — is empty, the response carries an empty_state envelope (kind, reason, next_step; multi-section responses instead use section-scoped variants such as accounts_empty_state) giving the authoritative reason it is empty and the recovery action. Read that envelope for the reason rather than inferring one — do not assume data is still syncing or settling. The response may also carry a top-level warnings array flagging data-health caveats (e.g. a connection to reconnect, or an unconfirmed check to retry); relay those caveats too.

• Transactions List Transactions

  List recent transactions with pagination, optionally filtered by account and date range. Returns merchant name, amount, category, and pending status for each transaction, plus line_items for a transaction that carries an itemisation. Best for browsing recent activity or getting a chronological view. For targeted lookups (e.g. 'find my Amazon charges'), prefer transactions__search_transactions instead. An order from a linked retailer account arrives as an ordinary transaction carrying line_items — the individual lines of that order. Each line carries description (the product name on a product line), line_amount and currency_code, plus quantity, unit_amount, sku, upc, image_url and category where the retailer supplies them, and kind naming what the line is — product, tax, shipping, delivery_fee, discount, fee, or unknown. category is the retailer's own wording for a product line, relayed verbatim: it is a display string, never a category key, never a member of a closed set, and never a value to group or filter against the transaction's own category, which is a different vocabulary. Only a product line carries one; a tax, shipping or delivery_fee line never does. Every LINE amount is an unsigned magnitude and kind carries the direction, so a discount is a credit rather than a negative number. The two aggregates are signed: itemised_total and unitemised_remainder, when present, say how much of the transaction the lines account for, a discount line subtracts from itemised_total, and a negative unitemised_remainder is legal and means the source itemised more than it charged. Only a retailer order is itemised: a bank or card transaction never carries line_items, and a retailer order is recorded from the retailer rather than derived from the card charge that paid for it, so never present line_items as the contents of a card charge. line_items are read-only on every surface — no tool creates, edits, splits, recategorises or tags a line, and no automation rule acts on one — while the retail transaction itself is ordinary and can be tagged, categorised and matched by rules like any other. An absent line_items means this response carries no itemisation for that transaction, never that the order had none: read enrichment_note before telling a user a purchase was not itemised. By default results include only posted/settled transactions; pending (authorization-hold) transactions are excluded. Pass include_pending=true to also return pending transactions dated within the last 7 days — each carries is_pending=true, its amount may change when it settles, and it is read-only: never pass a pending transaction id to a write tool. Older unsettled authorizations are never returned. A plan may limit reads to a rolling recent window of history; when that limit applies to this caller, older transactions outside the window are not returned even when explicitly requested by date. The response signals whenever the window clamped the results (history_window_applied) and then carries the date visible history starts (history_window_floor_date), how far back matching activity actually exists (history_window_earliest_date), and how many older transactions were withheld (history_window_hidden_count) — lead with the dates when relaying this, so the user learns how far their history really goes rather than only that some rows are missing. The earliest date and the count are each omitted when unknown (absent is NOT zero), and both are scoped to THIS request's own filters (account, category, search, date range), i.e. what was withheld from THIS query, not an account-wide total. So an empty or shortened result set does not necessarily mean no matching transactions ever existed — upgrading the plan reveals full history immediately. When the window clamped results AND the caller's plan was confirmed, the response also carries a structured upgrade affordance (history_window_upsell) naming the plan that unlocks the hidden history and the tool to call to upgrade — relay it to offer the user a concrete next step. If the plan could not be confirmed at read time (a transient fail-closed clamp that may have affected a paid caller), history_window_upsell is omitted; the response instead carries a warning that the history window could not be confirmed and to retry shortly — relay that caveat and do NOT attribute the clamp to the caller's plan. When a result — or a section of it — is empty, the response carries an empty_state envelope (kind, reason, next_step; multi-section responses instead use section-scoped variants such as accounts_empty_state) giving the authoritative reason it is empty and the recovery action. Read that envelope for the reason rather than inferring one — do not assume data is still syncing or settling. The response may also carry a top-level warnings array flagging data-health caveats (e.g. a connection to reconnect, or an unconfirmed check to retry); relay those caveats too. Session context from knowledge__get_financial_context_and_overview enriches these results with the user's profile, goals, and preferences.

• Accounts Check Account Balance

  Get the current and available balance for a specific account, including credit limit if applicable. Requires an account_group_key from accounts__list_financial_accounts. Use when the user asks about a specific account's balance rather than all accounts.

• Insights Analyze Spending

  Break down spending by category, merchant, account, week, or month. Each group carries amount, percent of total, and transaction count. Every amount carries its own currency_code, and groups are formed per currency as well as per label: a vault holding two currencies returns the same label once per currency. percent_of_total is a share of the total in that group's OWN currency. total_spending is a currency_code of 'Multi' when it sums groups in more than one currency — that number is a sum of magnitudes, not an amount of money, so report the groups rather than the total — and 'Unknown' when no currency could be determined. Never state a currency the response did not give you. group_by 'category', 'merchant' or 'account' returns the top_n highest-spending groups, highest first; across more than one currency the ranking runs within each currency, so the cut never drops a whole denomination and the order interleaves them. 'week' and 'month' ignore top_n and return one group per period that has spending, oldest first, never truncated. A gap in the series means no spending in that period, not an omitted group. A wide range returns many groups; narrow the period to bound the response. Week and month groups carry period_start and period_end: the dates covered, clamped to the requested range. Read those dates, not the label, when the span matters. The first and last group are commonly partial. A week label is a 7-day block counted from January 1, not an ISO week. period.start is the first date the response covers: the requested start date whenever the request names one, and — for 'all_time', or a custom range starting 0001-01-01, which name none — the date of the earliest transaction matching this call. It is omitted whenever no such date is available: beside empty groups the empty_state envelope explains why; beside non-empty groups the bound was unavailable, never that nothing matched. Divide total_spending.amount by the span from period.start to period.end for a per-day rate under any group_by, including 'category', 'merchant' or 'account', and only when its currency_code names a real currency: total_spending sums every group the period matched, before top_n removes any, so it is the whole of the spending and the rate is not understated. percent_of_total divides by that same untrimmed total within the group's own currency, so the returned groups need not add up to total_spending and their percentages need not reach 100 when top_n trimmed a tail. Drill from a category into its merchants with category_key. Use it for questions like 'where is my money going?'. Results include only posted/settled transactions; pending (authorization-hold) transactions are excluded. When a result — or a section of it — is empty, the response carries an empty_state envelope (kind, reason, next_step; multi-section responses instead use section-scoped variants such as accounts_empty_state) giving the authoritative reason it is empty and the recovery action. Read that envelope for the reason rather than inferring one — do not assume data is still syncing or settling. The response may also carry a top-level warnings array flagging data-health caveats (e.g. a connection to reconnect, or an unconfirmed check to retry); relay those caveats too. Session context from knowledge__get_financial_context_and_overview enriches these results with the user's profile, goals, and preferences.

• Transactions Search Transactions

  Search and filter transactions by merchant name, description, amount range, date range, and direction (debit/credit). Returns matching transactions with total count and sum — no arithmetic needed. sum always covers posted transactions only; when include_pending=true the pending share is reported separately as pending_count and pending_sum. Use for targeted questions like 'how much did I spend at Starbucks?', 'what was that $50 charge?', or 'show me all refunds this month'. Supports free-text search so exact merchant names are not required — but free-text does NOT match category names. To filter by category, first call transactions__list_spending_categories to resolve the category to its fcat_* key, then pass that key as category_key (set include_children=true to also include its subcategories). For browsing recent activity chronologically, prefer transactions__list_transactions instead. An order from a linked retailer account arrives as an ordinary transaction carrying line_items — the individual lines of that order. Each line carries description (the product name on a product line), line_amount and currency_code, plus quantity, unit_amount, sku, upc, image_url and category where the retailer supplies them, and kind naming what the line is — product, tax, shipping, delivery_fee, discount, fee, or unknown. category is the retailer's own wording for a product line, relayed verbatim: it is a display string, never a category key, never a member of a closed set, and never a value to group or filter against the transaction's own category, which is a different vocabulary. Only a product line carries one; a tax, shipping or delivery_fee line never does. Every LINE amount is an unsigned magnitude and kind carries the direction, so a discount is a credit rather than a negative number. The two aggregates are signed: itemised_total and unitemised_remainder, when present, say how much of the transaction the lines account for, a discount line subtracts from itemised_total, and a negative unitemised_remainder is legal and means the source itemised more than it charged. Only a retailer order is itemised: a bank or card transaction never carries line_items, and a retailer order is recorded from the retailer rather than derived from the card charge that paid for it, so never present line_items as the contents of a card charge. line_items are read-only on every surface — no tool creates, edits, splits, recategorises or tags a line, and no automation rule acts on one — while the retail transaction itself is ordinary and can be tagged, categorised and matched by rules like any other. An absent line_items means this response carries no itemisation for that transaction, never that the order had none: read enrichment_note before telling a user a purchase was not itemised. By default results include only posted/settled transactions; pending (authorization-hold) transactions are excluded. Pass include_pending=true to also return pending transactions dated within the last 7 days — each carries is_pending=true, its amount may change when it settles, and it is read-only: never pass a pending transaction id to a write tool. Older unsettled authorizations are never returned. A plan may limit reads to a rolling recent window of history; when that limit applies to this caller, older transactions outside the window are not returned even when explicitly requested by date. The response signals whenever the window clamped the results (history_window_applied) and then carries the date visible history starts (history_window_floor_date), how far back matching activity actually exists (history_window_earliest_date), and how many older transactions were withheld (history_window_hidden_count) — lead with the dates when relaying this, so the user learns how far their history really goes rather than only that some rows are missing. The earliest date and the count are each omitted when unknown (absent is NOT zero), and both are scoped to THIS request's own filters (account, category, search, date range), i.e. what was withheld from THIS query, not an account-wide total. So an empty or shortened result set does not necessarily mean no matching transactions ever existed — upgrading the plan reveals full history immediately. When the window clamped results AND the caller's plan was confirmed, the response also carries a structured upgrade affordance (history_window_upsell) naming the plan that unlocks the hidden history and the tool to call to upgrade — relay it to offer the user a concrete next step. If the plan could not be confirmed at read time (a transient fail-closed clamp that may have affected a paid caller), history_window_upsell is omitted; the response instead carries a warning that the history window could not be confirmed and to retry shortly — relay that caveat and do NOT attribute the clamp to the caller's plan. When a result — or a section of it — is empty, the response carries an empty_state envelope (kind, reason, next_step; multi-section responses instead use section-scoped variants such as accounts_empty_state) giving the authoritative reason it is empty and the recovery action. Read that envelope for the reason rather than inferring one — do not assume data is still syncing or settling. The response may also carry a top-level warnings array flagging data-health caveats (e.g. a connection to reconnect, or an unconfirmed check to retry); relay those caveats too. Session context from knowledge__get_financial_context_and_overview enriches these results with the user's profile, goals, and preferences.

• Insights Compare Spending Periods

  Compare spending between any two time periods side-by-side with pre-computed deltas and percentage changes. Group comparisons by category, merchant, or total. Use for questions like 'am I spending more this month than last?', 'how do my grocery costs compare to last year?', or 'which categories increased the most?'. Automatically warns about partial periods to prevent misleading comparisons. Results include only posted/settled transactions; pending (authorization-hold) transactions are excluded. When a result — or a section of it — is empty, the response carries an empty_state envelope (kind, reason, next_step; multi-section responses instead use section-scoped variants such as accounts_empty_state) giving the authoritative reason it is empty and the recovery action. Read that envelope for the reason rather than inferring one — do not assume data is still syncing or settling. The response may also carry a top-level warnings array flagging data-health caveats (e.g. a connection to reconnect, or an unconfirmed check to retry); relay those caveats too. Session context from knowledge__get_financial_context_and_overview enriches these results with the user's profile, goals, and preferences.

• Transactions List Recurring Charges

  List detected recurring transactions — subscriptions (Netflix, Spotify), bills (rent, utilities), and regular income (salary, freelance) — with estimated monthly amounts, frequency, and last-seen date. Includes monthly totals by type. Use for questions like 'what subscriptions am I paying for?', 'how much are my fixed monthly expenses?', or 'what’s my regular income?'. This is detected pattern metadata (the FirstSeen/LastSeen dates that identify a recurrence), not a row-level transaction list, so it is not subject to the free-plan history window that limits transactions__list_transactions/transactions__search_transactions. Results include only posted/settled transactions; pending (authorization-hold) transactions are excluded. Session context from knowledge__get_financial_context_and_overview enriches these results with the user's profile, goals, and preferences.

• Insights Get Cash Flow

  Analyze income, spending, and net cash flow over multiple weeks or months (up to 12 periods) with computed averages. Use for trend questions like 'am I saving more than last quarter?', 'how has my spending changed?', or 'what's my average monthly income?'. Returns pre-computed averages so you can narrate trends directly without doing math. Results include only posted/settled transactions; pending (authorization-hold) transactions are excluded. When a result — or a section of it — is empty, the response carries an empty_state envelope (kind, reason, next_step; multi-section responses instead use section-scoped variants such as accounts_empty_state) giving the authoritative reason it is empty and the recovery action. Read that envelope for the reason rather than inferring one — do not assume data is still syncing or settling. The response may also carry a top-level warnings array flagging data-health caveats (e.g. a connection to reconnect, or an unconfirmed check to retry); relay those caveats too. Session context from knowledge__get_financial_context_and_overview enriches these results with the user's profile, goals, and preferences.

• Insights Get Daily Financial Summary

  Get daily financial calendar for a month. Returns spending, income, bills/recurrences, and net per day, plus month totals and prior-month comparisons. Totals are broken down per currency (keyed by ISO-4217 code in totals_by_currency and each day's by_currency): a user's accounts may span several currencies, which are reported separately and never summed together. Use for calendar heatmaps, daily budgets, cash flow analysis, or questions like 'what did I earn and spend each day this month?'. These are aggregate daily totals, not a row-level transaction list, so they are not subject to the free-plan history window that limits transactions__list_transactions/transactions__search_transactions — a queried month's totals reflect all of that month's activity regardless of plan. Results include only posted/settled transactions; pending (authorization-hold) transactions are excluded. When a result — or a section of it — is empty, the response carries an empty_state envelope (kind, reason, next_step; multi-section responses instead use section-scoped variants such as accounts_empty_state) giving the authoritative reason it is empty and the recovery action. Read that envelope for the reason rather than inferring one — do not assume data is still syncing or settling. The response may also carry a top-level warnings array flagging data-health caveats (e.g. a connection to reconnect, or an unconfirmed check to retry); relay those caveats too. Session context from knowledge__get_financial_context_and_overview enriches these results with the user's profile, goals, and preferences.

• Insights Get Daily Category Spending

  Get a per-day, per-category spending breakdown for a calendar month. Returns one row per day-and-category combination with the spending amount, transaction count, and the user's category display name, plus month totals. Use for spending-calendar drill-downs and questions like 'which categories did I spend on each day this month?' or 'break down my daily spending by category'. For per-day totals of spending, income, and bills use insights__get_daily_financial_summary; for ranked category totals over a period use insights__analyze_spending. For the current month, totals apply a same-day rolling cutoff: rows dated after today are still returned but excluded from total_amount and transaction_count. Results include only posted/settled transactions; pending (authorization-hold) transactions are excluded. When a result — or a section of it — is empty, the response carries an empty_state envelope (kind, reason, next_step; multi-section responses instead use section-scoped variants such as accounts_empty_state) giving the authoritative reason it is empty and the recovery action. Read that envelope for the reason rather than inferring one — do not assume data is still syncing or settling. The response may also carry a top-level warnings array flagging data-health caveats (e.g. a connection to reconnect, or an unconfirmed check to retry); relay those caveats too. Session context from knowledge__get_financial_context_and_overview enriches these results with the user's profile, goals, and preferences.

• Insights Forecast Spending

  Estimate how much the user will spend by the end of the current period based on their spending pace so far. Returns: projected end-of-period total, daily spending rate, category-level breakdown with projections, and expected upcoming recurring charges (subscriptions, bills). Use for questions like 'how much will I spend this month?', 'am I on track with my budget?', or 'what recurring charges are coming up?'. The projection is based on current spending patterns and known recurring items — it is an estimate, not a guarantee. Results include only posted/settled transactions; pending (authorization-hold) transactions are excluded. When a result — or a section of it — is empty, the response carries an empty_state envelope (kind, reason, next_step; multi-section responses instead use section-scoped variants such as accounts_empty_state) giving the authoritative reason it is empty and the recovery action. Read that envelope for the reason rather than inferring one — do not assume data is still syncing or settling. The response may also carry a top-level warnings array flagging data-health caveats (e.g. a connection to reconnect, or an unconfirmed check to retry); relay those caveats too. Session context from knowledge__get_financial_context_and_overview enriches these results with the user's profile, goals, and preferences.

• Transactions List Spending Categories

  List all available spending categories organized in a parent/child hierarchy (e.g., 'Daily living' contains 'Groceries', 'Dining out', etc.). Each category has a unique key (the key field) that you MUST use when assigning categories via transactions__update_transactions or transactions__manage_automation_rules. Call this tool first whenever you need to categorize a transaction or create a rule with a set_category action — do not guess category keys.