How to connect Era-Context-MCP with Codex

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Create, rename, hide, unhide, delete, or merge spending categories. Display mutations (rename, emoji, description, spending type) of system categories are free on all plans. Custom category limits per plan — Context Basic (free): 2, Context Organize: 10, Context Automate: 50, Context Optimize: 100, Context Operate: 300. Use transactions__list_spending_categories first to get current category keys. When creating a category, provide a URL-safe slug (lowercase, hyphens allowed, 2-50 chars) and a parent category key under which to place it.

Update the category, merchant name, description, or review status on one or more transactions. The user's changes take priority over automatically detected values. BEFORE calling: use transactions__list_transactions or transactions__search_transactions to get transaction IDs, and call transactions__list_spending_categories to get valid category keys if changing the category. Use the clear_ options to undo a previous manual change and revert to the original value. For bulk automatic updates based on conditions, use transactions__manage_automation_rules instead.

Create and manage automation rules that automatically organize the user's transactions. Transaction-scope rules evaluate filters against each individual transaction as it arrives. Pattern-scope rules evaluate a pattern specification against a time-windowed batch of transactions to detect cross-transaction patterns such as transfers, recurring charges, spending anomalies, and frequency thresholds. Transaction-scope rules watch for transactions matching conditions you define (by merchant name, amount, category, tags, transaction type, date, or combinations using and/or/not logic) and then perform actions like assigning a category, adding/removing tags, renaming the merchant, hiding the transaction, flagging for review, updating the description, or marking as a transfer. Pattern-scope rules require a pattern_spec object and window_days parameter. Library pattern rules (like Transfer Detection, Recurring Detection, and Anomaly Detection) are created automatically and cannot be deleted, but you can enable, disable, or tune their behavior via user_overrides on update. Use the preview action to test filters or pattern specs against historical data before committing. BEFORE creating rules: call transactions__list_spending_categories to get category keys for set_category actions, and call transactions__manage_transaction_tags with list_tags to get tag keys for tag-related actions or filters. AFTER creating rules: the user's existing transactions are updated immediately by default (apply_retroactively defaults to true), and all future matching transactions will be processed automatically.

Create, list, update, or delete tags, and attach or detach them from transactions. Tags are custom labels the user attaches to transactions for organizing expenses by project, trip, goal, or any personal grouping (e.g., 'Vacation 2026', 'Tax Deductible', 'Side Project'). Use this tool when the user wants to create a new tag, see existing tags, or tag specific transactions. After creating a tag, attach it to specific transactions with the 'assign_tags' action (and detach with 'remove_tags'), or set up a rule to auto-tag matching transactions using transactions__manage_automation_rules.

List, confirm, or reject detected transfer links between the user's accounts. Transfer links are automatically detected when matching debit/credit transactions appear across different accounts (exact or near-match amounts within 3%). Use 'list' to see all detected transfers. Use 'confirm' when the user verifies a detected transfer is correct (upgrades confidence to 100%). Use 'reject' when a detected transfer is a false positive (removes the link and prevents re-detection). Transfer-tagged transactions are automatically excluded from spending and income analytics to prevent double-counting.

Get the user's current subscription plan, tier, usage against meter limits, and what the next tier up would unlock. Use for questions like 'what plan am I on?', 'how many API calls do I have left?', or 'what am I paying for?'. Call billing__list_plans if the user wants to compare all available tiers. The response distinguishes a scheduled full cancellation from a genuine tier downgrade via is_cancellation_pending — a downgrade also sets a pending tier but is not a cancellation. When is_cancellation_pending is true, call billing__uncancel_subscription to offer the user the winback path and keep their subscription active.

List what the user is actually being charged for right now, read live from Stripe, broken down by individual line item. Use for 'what am I paying for?', 'when does my subscription renew?', 'how much is my add-on?', or 'am I being charged twice?'. Each subscription carries one or more items, and price, billing period and renewal date are per ITEM, not per subscription: a plan item and an add-on item on the same subscription can bill on different cadences and renew on different dates, so answer renewal questions from the specific item's current_period_end and never from another item's. A user may also hold more than one subscription; when the list has more than one entry, say so plainly rather than describing only the first. An item with kind 'legacy' is on a price predating the current catalog: report its name and amount as given and do not offer to change its billing period. Call billing__list_payments for past invoices rather than inferring them from this response.

List the user's past invoices — what they were charged, when, for which service period, and whether each was paid. Use for 'what have I been charged?', 'when was I last billed?', or 'show me my receipts'. Amounts are in minor currency units (cents for USD). Pagination is forward-only and cursor-based, not page-numbered: pass the previous response's next_cursor back as cursor to get the next page, and stop when next_cursor is null (has_more is false). There is no total count and no way to jump to a page or go backwards — never invent a cursor value. This tool returns no invoice PDF or hosted invoice link, by design. If the user wants the actual document, send them to the billing portal, which authenticates them first.

List all available subscription plans with pricing, billing periods, feature comparisons relative to the user's current tier, and free trial eligibility. Use for questions like 'what plans are available?', 'how much does the automate plan cost?', or 'can I get a free trial?'. Returns each tier marked as upgrade, current, or downgrade. After the user picks a plan, call billing__upgrade to subscribe or change tiers directly. billing__preview_subscription_change and billing__confirm_subscription_change require an organize-tier-or-above subscription and preview then confirm the exact prorated cost of a change for an existing subscriber — call billing__upgrade instead if the user has no active subscription yet.

Start a subscription upgrade or plan change. Returns either a confirmation that the change was applied immediately (for existing subscribers changing tiers) or a secure checkout URL the user must visit to complete payment. Use when the user says 'I want to upgrade to automate', 'switch me to the yearly plan', or 'subscribe to organize'. Call billing__upgrade directly to subscribe for the first time or change tiers immediately; existing subscribers who already have an organize-tier-or-above subscription can instead call billing__preview_subscription_change first to show the prorated price before confirming with billing__confirm_subscription_change. Requires billing-write permission. After presenting a checkout URL to the user, consider polling billing__get_current_plan after 1-2 minutes to verify the upgrade completed.

Initiate subscription cancellation. This is a three-path retention gate. Step 1: Call WITHOUT a confirmation_key — the tool returns a retention offer with a 50% discount coupon for the next billing cycle and a confirmation key. Present this offer to the user. Step 2a: If the user accepts the discount, call AGAIN WITH the confirmation_key AND accept_offer=true — the tool applies the coupon to their subscription and returns the outcome. Step 2b: If the user declines, call AGAIN WITH the confirmation_key AND accept_offer=false (or omit accept_offer) — the tool returns the billing page URL where the user can complete cancellation manually. This tool does NOT cancel the subscription directly. Requires billing-write permission.

Un-cancel a subscription that Stripe holds a scheduled cancellation for, in either of the two mutually exclusive expressions Stripe stores one in: the cancel_at_period_end flag, or a concrete cancel_at instant with that flag false. Clears the scheduled cancellation and optionally applies a 50% off winback coupon for the next billing cycle. The user must have an active subscription that is currently scheduled to stop renewing. Returns the current tier and whether the coupon was applied. Requires billing-write permission.

Load the user's profile, complete financial snapshot (all account balances, net worth, this month vs. last month income/spending/net, top 5 spending categories), known facts, goals, preferences, and personalization state — all in one call. Typically the first tool called in a session to establish user context. Returns a personalization.guidance_quality field: when not 'ready', personalization.questions_to_unlock_better_guidance contains onboarding questions that improve guidance quality. For additional questions, call knowledge__get_pending_questions. Facts whose structured value carries "$type": "lookup", "lookupTarget": "connected-accounts" record the user's intent to source that value from their connected accounts; resolve the current amount against the accounts and totals_by_type arrays in this same response rather than surfacing the raw directive string. Related tools: insights__analyze_spending, transactions__search_transactions, insights__compare_spending_periods for deeper financial analysis. 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.

Record a fact, preference, goal, or observation about the user. Persistent across sessions and shared with all connected agents. Two modes: (1) prompted -- supply the slug and answer from knowledge__get_pending_questions; category is auto-derived. (2) Ambient -- supply a descriptive slug and category for facts discovered in conversation. Populate exactly one typed value field matching the answer_type, or set use_connected_accounts to source the value from the user's connected financial data.

Get the next onboarding questions to ask the user. Returns an ordered list of pending questions with each question's slug, display text, answer type, category, constraints, and a suggested_presentation field. Inspect suggested_presentation to decide how to present each question: when 'conversational', ask in natural language -- for single-select and country types, consider using your client's native question/picker tool (e.g., AskUserQuestion) for a better user experience. When 'embedded_ui', call knowledge__show_question_ui to present a visual input control (best for numeric, date, money, multi-select, compound, and scale types). After the user answers, record it via knowledge__remember. Tip: you can offer to extract answers from documents or images the user shares (pay stubs, tax forms, statements), or from facts you already know — not every question needs to be asked directly.

Present an onboarding question using a visual input control (slider, date picker, multi-select checklist, etc.). Best for answer types that benefit from structured widgets: numeric, date, money, multi-select, compound, and scale. Requires a client that supports MCP Apps embedded UI rendering. If your client is a CLI or terminal without embedded UI support, present the question conversationally or use your client's native question/picker tool instead. Call knowledge__get_pending_questions first to discover available question slugs and check each question's suggested_presentation field. Use this tool when suggested_presentation is 'embedded_ui'. For simple answer types (text, boolean, single-select, country, region), record the answer directly via knowledge__remember.

Skip or snooze an onboarding question. Use 'skip' when the user declines to answer a question (it may be re-surfaced later by the flow engine). Use 'snooze' when the user wants to defer the question for a specific number of days. Call knowledge__get_pending_questions first to discover available question slugs.

Warning: this cannot be undone — only call when you have high confidence the user wants to reset and re-surface all previously skipped or snoozed questions. This operation reverts all Skipped and Snoozed question states back to Pending so they will be re-surfaced by the flow engine. It does not delete any stored facts or assertions — only the skip/snooze state is reset. Call knowledge__get_pending_questions after a successful reset to obtain the newly re-surfaced questions.

Confirm or reject a fact that was inferred by the system. Use 'confirm' when the user agrees with an inferred assertion (upgrades confidence to 'confirmed'). Use 'reject' when the user disagrees -- optionally provide a corrected_value with the user's actual answer. Call knowledge__get_financial_context_and_overview first to see inferred assertions that need confirmation.

Retract or delete a previously recorded fact about the user. Use this when the user asks to forget or remove a specific piece of information. The assertion is marked as retracted (not physically deleted) so it appears in the audit history. Call knowledge__get_financial_context_and_overview first to find the slug of the fact to retract.

Get the version history of a specific fact about the user. Returns all versions of the assertion including supersessions, retractions, and confirmations. Use this when the user asks how a fact has changed over time or to audit the history of a specific piece of information. Call knowledge__get_financial_context_and_overview first to find assertion slugs.

Initiate a bank account connection flow. Opens a secure connection page that the user interacts with to link their bank account. Optionally accepts a connection_id to reconnect an existing connection that has become stale or requires re-authentication. Also accepts an assistant_name (your name, e.g. 'Claude') to personalize the experience. Use this when the user wants to connect a new bank account or fix a broken connection.

Get the user's referral link if they are enrolled in the referral program. Returns the shareable referral URL and affiliate ID for enrolled users, or indicates the user is not yet enrolled. Users must join the referral program before a link is available.

Get the user's referral performance statistics: visitors, conversions, earned commissions, and pending commissions. Use when the user asks about referral earnings, conversion rates, or how their referrals are performing.

Join the referral program by creating a Rewardful affiliate for the authenticated user. Returns the shareable referral URL and affiliate ID on success. Use when the user wants to start referring others and earning commissions.

Get a single-use SSO magic link to open the user's Rewardful affiliate dashboard. The link expires after approximately 1 minute and can only be used once. Use when the user wants to view detailed referral reporting, commission history, or manage their affiliate settings.

Move the user's referral programme onto a different track. Rewardful allows one affiliate per email, so this reassigns their existing affiliate rather than creating a second one — the user must already have joined (referral__join_referral_program) or this returns an error. Two destinations accept members: 'friends-family-usd' pays a fixed reward for each friend who subscribes, in the currency that user is billed in, and 'creator' pays 30% recurring commission for 12 months on each referred subscription. Naming 'friends-family-usd' selects the track only — the server assigns the campaign paying the user's own settled currency and the response reports the slug actually assigned, so read the currency off the result rather than off the request. Any other slug, including a campaign the deployment has retired, is refused with the list of destinations that would have worked.

Set the visibility of a single financial account. Pass visible=true to show an account or visible=false to hide it. Hidden accounts are excluded from analytics and summaries. Use accounts__list_financial_accounts (with include_hidden=true) to get the account_group_key. Accounts excluded by tier enforcement (tier_excluded) cannot be toggled — the user must use the swap operation or upgrade their plan via billing__list_plans. Showing an account when the user is at their tier limit is also blocked — use swap instead.

Record whether Era may proactively ask a bank connection's provider for fresh data on its own schedule. Set mode='disabled' when the user wants Era to stop reaching out to that bank between their own requests; set mode='enabled' to allow it again. This does NOT stop the connection: webhook updates, reconciliation and reads of data the provider already holds continue either way, and an on-demand refresh the user asks for is always honoured. The instruction is recorded for any connection the user owns — including one whose provider is never proactively contacted, and one whose plan does not include the proactive lane — so it survives a plan change and takes effect if the situation changes. Use connections__list_connections to obtain the connection_id. The response reports what was recorded AND whether it changes anything today, so say that back to the user rather than implying an effect that will not occur.

Permanently disconnect a bank institution. This is a DESTRUCTIVE, IRREVERSIBLE operation that severs the link to the financial institution and stops all future data syncs. All accounts associated with this connection will be soft-deleted and excluded from analytics. Use connections__list_connections to identify the connection_id for the institution. After disconnecting, use connections__connect_bank_account to reconnect where the provider supports reconnecting (some connection types can't be reconnected on demand — the disconnect response says which).

Get contextual help and onboarding guidance for Era Context. Use when the user asks how to use the platform, what capabilities are available, how to get started, how to connect accounts, what they can ask, or questions about privacy or troubleshooting. Returns authoritative help content — prefer this over generating answers from memory.

Manage financial accounts in the user's universe — both manually tracked accounts and accounts synced from a connected banking provider. Actions: 'create' a new manual account (manual only), 'update' to change account properties (account_name is account-type-agnostic; account_type/institution_name/account_number_mask are manual-only), 'delete' to soft-delete a manual account (manual only), 'set_balance' to record a balance snapshot (manual only). On update, supplying 'account_name' writes a user-supplied display-name override that applies on top of any institution-supplied name and works for any account type — manual or connected. Supplying 'clear_account_name=true' removes the override, reverting to the institution-supplied name. The two are mutually exclusive. The account_type enum in the schema lists all valid types. Use accounts__list_financial_accounts to obtain the account_group_key for existing accounts.

Batch-manage transactions on a manually tracked account. Send an array of operations (create, update, delete) in a single call — ideal for bulk imports. All operations share one account_group_key. Once the request is read, operations are processed sequentially with partial-success semantics: a business-rule failure on one operation does not stop the others, and each gets its own verdict. A value that is malformed for its declared type — a date that is not yyyy-MM-dd, a non-integer amount — is rejected before any operation runs, so the whole call fails naming the offending operation index and nothing is written. Set preview_only=true to validate without writing. Use accounts__list_financial_accounts to obtain the account_group_key, and transactions__list_transactions to obtain the transaction_group_key. Before creating transactions, call transactions__list_spending_categories to obtain a valid category_key (fcat_xxx format). A plan may limit reads to a rolling recent window of history. When that limit applies to this caller, a transaction dated before the window is still stored and syncs normally — the write is never blocked, delayed, or rejected by the window. It simply will not appear in transactions__list_transactions/transactions__search_transactions results until the plan is upgraded or the date rolls back into the window. The response signals when this applies to a specific transaction and, whenever the window could be confirmed, leads that signal with the date visible history starts — relay that date rather than only the fact of exclusion.

Import transactions from inline CSV text into a manual account. Supports auto-detection of common formats or explicit format hints. Partial-success semantics: rows that fail validation are reported individually. Set preview_only=true to validate without importing. PROTOCOL — before calling, do the categorisation work up front so the CSV you submit is already aligned with the user's category landscape: (1) call accounts__list_financial_accounts to obtain the account_group_key for the target manual account; (2) call transactions__list_spending_categories to enumerate the user's effective categories — both system and custom (Origin="user"); (3) inspect the source CSV header to see whether it carries a category column; (4) when you write the CSV content into csv_content, set the Category column on each row to text that maps cleanly onto the categories surfaced in step 2. Composing the CSV deliberately at submission time keeps the import deterministic and avoids a follow-up cleanup pass. A plan may limit reads to a rolling recent window of history. When that limit applies to this caller, a transaction dated before the window is still stored and syncs normally — the write is never blocked, delayed, or rejected by the window. It simply will not appear in transactions__list_transactions/transactions__search_transactions results until the plan is upgraded or the date rolls back into the window. The response signals when this applies to a specific transaction and, whenever the window could be confirmed, leads that signal with the date visible history starts — relay that date rather than only the fact of exclusion.

Toggle balance backfill for an account group. When enabled, balances are derived from cumulative transaction history rather than relying solely on explicit balance snapshots. This is useful for accounts that have transaction data but lack balance snapshots (e.g., CSV-imported accounts). This feature is only supported for manual accounts. Use accounts__list_financial_accounts to obtain the account_group_key.

Trigger an on-demand data resync for a bank connection. This fetches the latest transaction and balance data from supported banks — most major institutions support on-demand refresh, though it may take a few minutes for data to arrive. Possible outcomes: (1) resync queued successfully — check back shortly for updated data, (2) the bank requires the user to re-authenticate first — a widget link is returned that the user must open in the app to authenticate before the latest data can be fetched, (3) user's plan does not include on-demand resync (available on Automate tier or with Fast-Lane Data Sync add-on; use billing__list_plans to explore upgrade options), (4) data was already refreshed recently — next refresh available after the indicated time, (5) connection not found or not owned by the user. Use connections__list_connections to obtain the connection_id.

List every one of the user's connections with an honest, provider-agnostic status for each: whether it is healthy, syncing with no data yet, needs reconnecting, is currently disconnected, or one of several other narrower states — see each row's state for the exact one. This is the discover hop of the connection recovery loop — call this first to get each connection's connection_id, then act on a specific connection with connections__trigger_connection_resync, connections__connect_bank_account, or connections__disconnect_institution. Unlike accounts__list_financial_accounts, this tool's subject is the connection roster itself, not the accounts beneath it — use it to answer "what is connected and is anything broken?" rather than "what accounts do I have?". A connection may link a retailer account rather than a bank. An order from a linked retailer account arrives as an ordinary transaction carrying line_items — the individual lines of that order, and the two transaction read tools return those lines. A retailer link reports no balance and does not count toward net worth, and retailer linking is available in the US only.

Get the caller's own nurture (lifecycle email) campaign enrollment status — which campaigns they are currently enrolled in, their progress through each, and whether they have unsubscribed. Use for questions like 'what emails am I signed up for?' or 'am I subscribed to X?'. Call nurture__set_subscription to change the subscription state for a specific campaign.

Subscribe the caller to, or unsubscribe them from, a nurture (lifecycle email) campaign. Takes effect immediately — no confirmation step, and always reversible by calling this tool again with the opposite value. Unsubscribing from a campaign the caller was never enrolled in is a safe no-op. Call nurture__get_my_status first to see the caller's current campaigns and subscription state.