--- canonical_url: "https://docs.composio.dev/toolkits/era_context_mcp" markdown_url: "https://docs.composio.dev/toolkits/era_context_mcp.md" product: "platform" version: null last_updated: null --- # Era Context MCP Era Context MCP lets authorized agents analyze personal finances, manage financial context, and perform approved account, transaction, knowledge, connection, and billing workflows. - **Category:** model context protocol - **Auth:** DCR_OAUTH - **Composio-managed OAuth available?** No - **Tools:** 51 - **Triggers:** 0 - **Slug:** `ERA_CONTEXT_MCP` - **Version:** 20260924_00 ## Tools ### Accounts check account balance **Slug:** `ERA_CONTEXT_MCP_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. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `account_group_key` | string | Yes | The account group projection key. Obtain from accounts__list_financial_accounts (the account_group_key field). | ### Accounts list financial accounts **Slug:** `ERA_CONTEXT_MCP_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. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `include_hidden` | string | No | Set to true to also show accounts the user has chosen to hide. Default: false (only visible accounts). | ### Accounts manage account **Slug:** `ERA_CONTEXT_MCP_ACCOUNTS__MANAGE_ACCOUNT` 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. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `action` | string ("create" | "update" | "delete" | "set_balance") | Yes | What to do: 'create' adds a new manual account, 'update' changes account properties (account_name applies to any account type; other fields are manual-only), 'delete' soft-deletes a manual account and its transactions, 'set_balance' records a balance snapshot on a manual account. | | `currency` | string ("usd" | "eur" | "gbp" | "jpy" | "cad" | "aud" | "chf" | "cny" | "hkd" | "nzd" | "sek" | "krw" | "sgd" | "nok" | "mxn" | "inr" | "brl" | "zar" | "uah" | "pln" | "dkk" | "czk" | "huf" | "ron" | "bgn" | "bhd" | "qar" | "aed" | "try" | "thb" | "myr" | "php" | "btc" | "eth" | "usdt" | "usdc" | "bnb" | "xrp" | "ada" | "sol" | "unknown" | "multi") | No | ISO 4217 currency for the account (required for create). | | `as_of_date` | string | No | As-of date for the balance record in ISO 8601 format (e.g., "2026-04-15"). Defaults to today if not specified. Optional, set_balance only. | | `account_name` | string | No | The user-supplied display name (e.g., "Home Mortgage", "Savings Jar"). Required for create. On update, applies to any account type — manual or connected — and writes a user-layer override that surfaces as the effective name; the institution-supplied name is preserved underneath. Mutually exclusive with 'clear_account_name'. | | `account_type` | string ("unknown" | "checking" | "savings" | "money_market" | "cd" | "credit_card" | "line_of_credit" | "brokerage" | "ira_traditional" | "ira_roth" | "retirement401k" | "hsa" | "mortgage" | "auto_loan" | "student_loan" | "personal_loan" | "crypto" | "real_estate" | "manual_asset" | "manual_liability") | No | The account type classification. Required for create (manual). On update: manual accounts only — supplying this for a connected account is rejected. | | `balance_currency` | string ("usd" | "eur" | "gbp" | "jpy" | "cad" | "aud" | "chf" | "cny" | "hkd" | "nzd" | "sek" | "krw" | "sgd" | "nok" | "mxn" | "inr" | "brl" | "zar" | "uah" | "pln" | "dkk" | "czk" | "huf" | "ron" | "bgn" | "bhd" | "qar" | "aed" | "try" | "thb" | "myr" | "php" | "btc" | "eth" | "usdt" | "usdc" | "bnb" | "xrp" | "ada" | "sol" | "unknown" | "multi") | No | ISO 4217 currency for the balance (required for set_balance). | | `institution_name` | string | No | Institution name for display and fingerprint matching (e.g., "Chase", "Fidelity"). On update: manual accounts only. | | `account_group_key` | string | No | The account group projection key identifying the account. Required for update, delete, and set_balance. Obtain from accounts__list_financial_accounts (the account_id field). | | `amount_minor_units` | string | No | The balance amount in integer minor units (e.g., 150050 for $1,500.50, or 1000 for 1000 JPY). Required for set_balance. Positive = asset; negative = liability. | | `clear_account_name` | boolean | No | On update: set to true to remove a previously applied user account-name override, reverting the display name to the institution-supplied value (or empty when no provider name exists). Mutually exclusive with 'account_name'. Account-type-agnostic. | | `account_number_mask` | string | No | Partial account number (last 4 digits). Do NOT supply the full account number. On update: manual accounts only. | | `initial_balance_minor_units` | string | No | Starting balance in integer minor units (e.g., 150050 for $1,500.50, or 1000 for 1000 JPY). Positive = asset; negative = liability. Optional, create only. | ### Accounts set account visibility **Slug:** `ERA_CONTEXT_MCP_ACCOUNTS__SET_ACCOUNT_VISIBILITY` 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. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `visible` | boolean | Yes | Set to true to show the account (Owner scope) or false to hide it (UserExcluded scope). | | `account_group_key` | string | Yes | The account group projection key. Obtain from accounts__list_financial_accounts (the account_group_key field). | ### Accounts toggle balance backfill **Slug:** `ERA_CONTEXT_MCP_ACCOUNTS__TOGGLE_BALANCE_BACKFILL` 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. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `enable` | boolean | Yes | Set to true to enable balance derivation from transaction history. Set to false to disable and revert to snapshot-only balance behavior. | | `account_group_key` | string | Yes | The account group projection key identifying the target account group. Obtain from accounts__list_financial_accounts (the account_id field). Must be a manual account. | ### Billing cancel subscription **Slug:** `ERA_CONTEXT_MCP_BILLING__CANCEL_SUBSCRIPTION` 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. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `reason` | string | Yes | Why the user wants to cancel. Summarize their stated reason concisely. | | `accept_offer` | string | No | Set to true to accept the retention discount offer. Set to false or omit to decline and receive the billing page URL for manual cancellation. Only used on the second call alongside confirmation_key. | | `confirmation_key` | string | No | The confirmation key from the first call. Omit on first call to receive a retention offer; pass it on the second call along with accept_offer. | ### Billing get current plan **Slug:** `ERA_CONTEXT_MCP_BILLING__GET_CURRENT_PLAN` 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. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `currency` | string | No | Which currency to show the amounts in, as an ISO 4217 code (e.g. 'eur', 'gbp'). Optional: omit it and the amounts are shown in the currency this platform can tell the user settles in — the one their live subscriptions are billed in, or, for a user holding no live subscription, the one their past subscriptions settled in — and in the default currency only where it can tell neither, or tells more than one. That is the same currency the response reports as settled_currency, so a null settled_currency means the amounts are in the default currency. A code outside the supported set is rejected rather than substituted, and the rejection names the codes that are supported. | ### Billing list payments **Slug:** `ERA_CONTEXT_MCP_BILLING__LIST_PAYMENTS` 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. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | string | No | Maximum invoices to return on this page. Values outside the supported range are clamped server-side, so an out-of-range value degrades to the nearest supported page size rather than failing. | | `cursor` | string | No | Opaque pagination cursor from the previous page's next_cursor. Omit for the first page. Echo it back exactly as received — it is not an offset and cannot be constructed or incremented. | ### Billing list plans **Slug:** `ERA_CONTEXT_MCP_BILLING__LIST_PLANS` 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. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `currency` | string | No | Which currency to show the plan amounts in, as an ISO 4217 code (e.g. 'eur', 'gbp'). Optional: omit it and the amounts are shown in the currency this platform can tell the user settles in — the one their live subscriptions are billed in, or, for a user holding no live subscription, the one their past subscriptions settled in — and in the default currency only where it can tell neither, or tells more than one. That is the same currency the response reports as settled_currency, so a null settled_currency means the amounts are in the default currency. A code outside the supported set is rejected rather than substituted, and the rejection names the codes that are supported. | | `product_key` | string | No | Which product to explore plan options for (e.g., 'hub', 'quant'). Defaults to 'hub' if omitted. | ### Billing list subscriptions **Slug:** `ERA_CONTEXT_MCP_BILLING__LIST_SUBSCRIPTIONS` 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. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `reason` | string | No | Optional free-text note stating, in one short sentence, why you are calling this tool. It does not affect the result and is recorded only for diagnostics. This tool takes no other input: do not put data, filters, or parameters here, and omit it entirely if you have nothing to say. Do not include personal or financial details. | ### Billing uncancel subscription **Slug:** `ERA_CONTEXT_MCP_BILLING__UNCANCEL_SUBSCRIPTION` 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. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `apply_coupon` | boolean | No | Whether to apply the 50% off winback coupon during the uncancel. Defaults to true. Set to false if the user does not want the discount. | ### Billing upgrade **Slug:** `ERA_CONTEXT_MCP_BILLING__UPGRADE` 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. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `currency` | string | No | Which currency to bill the subscription in, as an ISO 4217 code (e.g. 'eur', 'gbp'). Optional: omit it and the subscription is billed in whatever currency this account already settles in. Naming a different currency is refused rather than applied whenever this platform can tell which single currency is in force — from the subscription a tier change would alter, or from the account's own settlement history; where it can tell from neither, or the history holds more than one currency, the purchase proceeds. A code outside the supported set is rejected rather than substituted; the rejection names the codes that are supported. | | `coupon_id` | string | No | Optional Stripe coupon ID from Rewardful for referral discounts. Ignored when a promotion code is also provided. | | `product_key` | string | No | Which product to upgrade (e.g., 'hub', 'quant'). Defaults to 'hub' if omitted. | | `target_plan` | string | Yes | Which plan to subscribe to (e.g., 'organize', 'automate', 'optimize'). Use billing__list_plans to see available plans. | | `billing_period` | string ("monthly" | "quarterly" | "yearly") | Yes | How often to bill: 'monthly', 'quarterly', or 'yearly'. | | `promotion_code` | string | No | Optional promotion code to apply a discount at checkout (e.g., 'SAVE50'). Omit to let the user enter one manually. | | `client_reference_id` | string | No | Optional client reference ID for referral attribution. Passed through to Stripe unchanged. | ### Connections connect bank account **Slug:** `ERA_CONTEXT_MCP_CONNECTIONS__CONNECT_BANK_ACCOUNT` 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. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `provider` | string | No | Optional banking provider identifier for this connection. Omit to use the platform's default provider unless you have a specific provider requirement. | | `connection_id` | string | No | Optional existing connection ID for reconnection flows. Provide this to reconnect a stale or broken connection instead of creating a new one. Get connection IDs from connections__list_connections. | | `assistant_name` | string | No | Your name or the name of the AI assistant being used (e.g. 'Claude', 'ChatGPT'). This helps personalize the connection experience for the user. | ### Connections disconnect institution **Slug:** `ERA_CONTEXT_MCP_CONNECTIONS__DISCONNECT_INSTITUTION` 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). #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `connection_id` | string | Yes | The connection ID of the institution to disconnect. Obtain from connections__list_connections (the connection_id field on each connection entry). | ### Connections list connections **Slug:** `ERA_CONTEXT_MCP_CONNECTIONS__LIST_CONNECTIONS` 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. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `reason` | string | No | Optional free-text note stating, in one short sentence, why you are calling this tool. It does not affect the result and is recorded only for diagnostics. This tool takes no other input: do not put data, filters, or parameters here, and omit it entirely if you have nothing to say. Do not include personal or financial details. | ### Connections set proactive sync mode **Slug:** `ERA_CONTEXT_MCP_CONNECTIONS__SET_PROACTIVE_SYNC_MODE` 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. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `mode` | string ("enabled" | "disabled") | Yes | 'disabled' to stop Era proactively contacting this bank on its own schedule; 'enabled' to allow it. Repeating the instruction the connection already carries is a no-op — it records nothing and adds nothing to the user's history. | | `connection_id` | string | Yes | The connection projection key identifying the bank connection. Obtain from connections__list_connections (the connection_id field on each connection entry). | ### Connections trigger connection resync **Slug:** `ERA_CONTEXT_MCP_CONNECTIONS__TRIGGER_CONNECTION_RESYNC` 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. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `connection_id` | string | Yes | The connection projection key identifying the bank connection to resync. Obtain from connections__list_connections (the connection_id field on each connection entry). | ### Help get help **Slug:** `ERA_CONTEXT_MCP_HELP__GET_HELP` 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. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `topic` | string ("getting_started" | "connecting_accounts" | "what_can_i_ask" | "privacy_and_security" | "troubleshooting") | Yes | The help topic to retrieve. Use 'getting_started' for first-time users, 'connecting_accounts' for account linking guidance, 'what_can_i_ask' for example prompts, 'privacy_and_security' for data handling details, or 'troubleshooting' for common issues. | ### Insights analyze spending **Slug:** `ERA_CONTEXT_MCP_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. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `top_n` | string | No | Number of groups to return with group_by 'category', 'merchant' or 'account': the top N by amount, highest first, ranked within each currency when the vault holds more than one. Default 10. The 1-50 bound limits the input value on every grouping. It does not cap 'week' or 'month' groups, which ignore top_n. | | `period` | string ("this_week" | "this_month" | "last_month" | "last_7_days" | "last_30_days" | "last_90_days" | "this_year" | "last_year" | "custom" | "all_time") | No | Time range for the breakdown. Use 'custom' with period_start/period_end for a specific date range. | | `group_by` | string ("category" | "merchant" | "account" | "week" | "month") | No | How to group the spending: 'category' (e.g., Groceries, Transportation), 'merchant' (e.g., Amazon, Starbucks), 'account' (by bank account), 'week' or 'month' (spending over time). | | `period_end` | string | No | Custom end date (YYYY-MM-DD). Used when period is 'custom'. Format: yyyy-MM-dd. | | `category_key` | string | No | Optional fcat_* category KEY (not a display name) to drill into one category. To get keys, call with group_by='category' and include_subcategories=true; each parent category returns its stable category_key. Pass one back here with group_by='merchant' to see the merchants that drove it. Keys are also listed by transactions__list_spending_categories (the key field). Omit to include all categories. | | `period_start` | string | No | Custom start date (YYYY-MM-DD). Used when period is 'custom'. Format: yyyy-MM-dd. | | `account_group_key` | string | No | Filter to a specific account. Pass the account group projection key from accounts__list_financial_accounts (the account_group_key field). | | `include_subcategories` | string | No | When true and group_by is 'category', groups results by parent category with subcategory breakdown. Has no effect on any other grouping, including on top_n. | ### Insights compare spending periods **Slug:** `ERA_CONTEXT_MCP_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. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `group_by` | string ("total" | "category" | "merchant") | No | How to break down the comparison: 'total' shows one overall comparison, 'category' compares each spending category, 'merchant' compares each merchant. | | `period_a` | string ("this_week" | "this_month" | "last_month" | "last_7_days" | "last_30_days" | "last_90_days" | "this_year" | "last_year") | No | The first time period to compare (shown as the 'current' or 'newer' period in the results). | | `period_b` | string ("this_week" | "this_month" | "last_month" | "last_7_days" | "last_30_days" | "last_90_days" | "this_year" | "last_year") | No | The second time period to compare against (shown as the 'baseline' or 'older' period). | | `category_key` | string | No | Optional fcat_* category KEY (not a display name) to compare only that category's spending between the two periods. Obtain the key from transactions__list_spending_categories (the key field) or reuse a category_key returned by insights__analyze_spending. Omit to compare across all categories. | | `account_group_key` | string | No | Filter to a specific account. Pass the account group projection key from accounts__list_financial_accounts (the account_group_key field). | ### Insights forecast spending **Slug:** `ERA_CONTEXT_MCP_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. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `period` | string ("this_month" | "last_month" | "last_30_days" | "this_year") | No | The time period to project spending for. 'this_month' is most common. | | `account_group_key` | string | No | Limit the projection to a specific account. Pass the account group projection key from accounts__list_financial_accounts (the account_group_key field). Omit to project across all accounts. | ### Insights get cash flow **Slug:** `ERA_CONTEXT_MCP_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. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `granularity` | string ("week" | "month") | No | Whether to show cash flow by 'week' or 'month'. | | `num_periods` | string | No | How many periods to include (e.g., 6 months, 12 weeks). Default: 6, max: 12. | | `account_group_key` | string | No | Filter to a specific account. Pass the account group projection key from accounts__list_financial_accounts (the account_group_key field). Omit to see cash flow across all accounts. | ### Insights get daily category spending **Slug:** `ERA_CONTEXT_MCP_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. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `year` | string | No | Year of the month to query. Defaults to the current year. | | `month` | string | No | Month number (1-12). Defaults to the current month. | ### Insights get daily financial summary **Slug:** `ERA_CONTEXT_MCP_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. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `year` | string | No | Year of the month to query. Defaults to the current year. | | `month` | string | No | Month number (1-12). Defaults to the current month. | | `category_key` | string | No | Optional fcat_* category key to filter daily totals by a specific category. Omit to get unfiltered totals. | ### Knowledge confirm or reject inference **Slug:** `ERA_CONTEXT_MCP_KNOWLEDGE__CONFIRM_OR_REJECT_INFERENCE` 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. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `slug` | string | Yes | The slug of the inferred assertion to confirm or reject. Get assertion slugs from knowledge__get_financial_context_and_overview. | | `action` | string ("confirm" | "reject") | Yes | The action to take: 'confirm' to accept the inferred value, or 'reject' to dispute it. | | `instance_id` | string | No | Instance identifier for repeatable assertions. Only needed when multiple instances exist for the same slug. | | `corrected_value` | string | No | The user's corrected value when rejecting an inference (e.g., the system inferred '$5,000/mo' but the user's actual income is '$8,500/mo'). Only used when action is 'reject'. | ### Knowledge defer question **Slug:** `ERA_CONTEXT_MCP_KNOWLEDGE__DEFER_QUESTION` 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. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `action` | string ("skip" | "snooze") | Yes | The action to take: 'skip' to decline the question, or 'snooze' to defer it for a number of days. | | `pack_slug` | string | No | The question pack slug containing this question. Defaults to 'financial-profile-v1' if omitted. | | `snooze_days` | string | No | Number of days to snooze the question (required when action is 'snooze'). The question will be re-surfaced after this many days. | | `question_slug` | string | Yes | The slug of the question to skip or snooze. Get available slugs from knowledge__get_pending_questions. | ### Knowledge forget **Slug:** `ERA_CONTEXT_MCP_KNOWLEDGE__FORGET` 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. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `slug` | string | Yes | The slug of the fact to retract. Get assertion slugs from knowledge__get_financial_context_and_overview. | | `pack_slug` | string | No | The question pack slug for flow progress recalculation when retracting an answer to a prompted question. Defaults to 'financial-profile-v1' if omitted. | | `instance_id` | string | No | Instance identifier for repeatable assertions. Only needed when multiple instances exist for the same slug. | ### Knowledge get financial context and overview **Slug:** `ERA_CONTEXT_MCP_KNOWLEDGE__GET_FINANCIAL_CONTEXT_AND_OVERVIEW` 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. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `tags` | string | No | Filter assertions to those matching specific tags (e.g., ['tax-relevant']). Omit to return all assertions regardless of tags. | | `status` | string ("active" | "superseded" | "retracted" | "draft") | No | Filter assertions by lifecycle status: 'active' (current facts), 'superseded' (replaced by newer facts), 'retracted' (withdrawn), or 'draft' (not finalized). Omit to return only active assertions. | | `category` | string | No | Filter assertions to a specific category (e.g., 'financial', 'preferences', 'goals'). Omit to return all categories. | | `pack_slug` | string | No | The question pack slug for completion progress data. Defaults to 'financial-profile-v1' if omitted. | ### Knowledge get pending questions **Slug:** `ERA_CONTEXT_MCP_KNOWLEDGE__GET_PENDING_QUESTIONS` 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. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `max_count` | string | No | Maximum number of questions to return. Defaults to 5 if omitted. | | `pack_slug` | string | No | The question pack slug to retrieve questions from. Defaults to 'financial-profile-v1' if omitted. | ### Knowledge recall history **Slug:** `ERA_CONTEXT_MCP_KNOWLEDGE__RECALL_HISTORY` 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. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `slug` | string | Yes | The slug of the fact to retrieve history for. Get assertion slugs from knowledge__get_financial_context_and_overview. | | `instance_id` | string | No | Instance identifier for repeatable assertions. Only needed when multiple instances exist for the same slug. | ### Knowledge remember **Slug:** `ERA_CONTEXT_MCP_KNOWLEDGE__REMEMBER` 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. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `slug` | string | Yes | The machine-readable identifier. For prompted questions, use the slug from knowledge__get_pending_questions. | | `tags` | string | No | Optional tags for additional categorization (e.g., ['tax-relevant', 'high-priority']). | | `source` | string ("prompted" | "conversational" | "inferred" | "observed" | "imported") | No | How this fact was captured: 'prompted' (user answered a question), 'conversational' (discovered during chat), 'inferred' (derived by agent), 'observed' (computed from data), or 'imported' (external source). Defaults to 'conversational' if omitted. | | `category` | string ("identity" | "income-and-employment" | "household" | "assets-and-debts" | "goals" | "preferences" | "behavioral") | No | The logical grouping category. Auto-derived for prompted questions; required for ambient facts. | | `modality` | string ("definite" | "aspirational" | "conditional") | No | The nature of the assertion: 'definite' (a stated fact), 'aspirational' (a goal or intention), or 'conditional' (contingent on something). Defaults to 'definite' if omitted. | | `pack_slug` | string | No | Question pack slug for flow tracking. Defaults to 'financial-profile-v1'. | | `confidence` | string ("definitive" | "confirmed" | "inferred" | "observed") | No | How certain the system is about this fact: 'definitive' (user explicitly stated), 'confirmed' (inferred and user confirmed), 'inferred' (agent derived, not yet confirmed), or 'observed' (computed from data). Defaults to 'definitive' if omitted. | | `date_value` | string | No | Date value for date answer type (YYYY-MM-DD). Format: yyyy-MM-dd. | | `text_value` | string | No | String value for text, text-multiline, single-select, multi-select (comma-separated), country (ISO alpha-2), and region answer types. | | `valid_time` | string | No | When this fact became true in the user's life (YYYY-MM-DD). Omit if the fact has no specific start date. Format: yyyy-MM-dd. | | `answer_type` | string ("text" | "text-multiline" | "number" | "money" | "money-periodic" | "money-relative" | "date" | "single-select" | "multi-select" | "boolean" | "scale" | "country" | "region") | Yes | The structural type. For prompted questions, use the answer_type from knowledge__get_pending_questions. | | `instance_id` | string | No | Instance identifier for repeatable facts that can have multiple values (e.g., 'checking-1', 'savings-2' for account-related facts). Omit for single-value facts. | | `money_value` | string | No | Money value for money answer type. | | `valid_until` | string | No | When this fact should be considered stale and re-asked (YYYY-MM-DD). Omit if the fact does not expire. Format: yyyy-MM-dd. | | `boolean_value` | string | No | Boolean value for boolean answer type. | | `numeric_value` | string | No | Numeric value for number and scale answer types. | | `money_periodic_value` | string | No | Periodic money value for money-periodic answer type (amount + currency + frequency). | | `money_relative_value` | string | No | Relative money value for money-relative answer type (amount + currency + direction). | | `use_connected_accounts` | string ("connected-accounts") | No | When the user wants the answer sourced from their connected financial accounts rather than a typed value, set this to "connected-accounts". Mutually exclusive with all typed value fields (text_value, numeric_value, boolean_value, date_value, money_value, money_periodic_value, money_relative_value). Use for balance and debt questions where the answer is available from the user's linked accounts. | ### Knowledge reset pack questions **Slug:** `ERA_CONTEXT_MCP_KNOWLEDGE__RESET_PACK_QUESTIONS` 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. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `pack_slug` | string | No | The question pack slug to reset. Defaults to 'financial-profile-v1' if omitted. | ### Knowledge show question ui **Slug:** `ERA_CONTEXT_MCP_KNOWLEDGE__SHOW_QUESTION_UI` 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. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `pack_slug` | string | No | The question pack slug containing this question. Defaults to 'financial-profile-v1' if omitted. | | `question_slug` | string | Yes | The slug of the question to present as a visual form. Get available slugs from knowledge__get_pending_questions. | ### Nurture get my status **Slug:** `ERA_CONTEXT_MCP_NURTURE__GET_MY_STATUS` 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. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `reason` | string | No | Optional free-text note stating, in one short sentence, why you are calling this tool. It does not affect the result and is recorded only for diagnostics. This tool takes no other input: do not put data, filters, or parameters here, and omit it entirely if you have nothing to say. Do not include personal or financial details. | ### Nurture set subscription **Slug:** `ERA_CONTEXT_MCP_NURTURE__SET_SUBSCRIPTION` 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. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `subscribed` | boolean | Yes | Set to true to subscribe (resubscribe if previously unsubscribed) or false to unsubscribe. | | `campaign_id` | string | Yes | The campaign identifier. Obtain from nurture__get_my_status's response. | ### Referral get dashboard sso **Slug:** `ERA_CONTEXT_MCP_REFERRAL__GET_DASHBOARD_SSO` 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. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `reason` | string | No | Optional free-text note stating, in one short sentence, why you are calling this tool. It does not affect the result and is recorded only for diagnostics. This tool takes no other input: do not put data, filters, or parameters here, and omit it entirely if you have nothing to say. Do not include personal or financial details. | ### Referral get referral link **Slug:** `ERA_CONTEXT_MCP_REFERRAL__GET_REFERRAL_LINK` 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. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `reason` | string | No | Optional free-text note stating, in one short sentence, why you are calling this tool. It does not affect the result and is recorded only for diagnostics. This tool takes no other input: do not put data, filters, or parameters here, and omit it entirely if you have nothing to say. Do not include personal or financial details. | ### Referral get referral stats **Slug:** `ERA_CONTEXT_MCP_REFERRAL__GET_REFERRAL_STATS` 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. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `reason` | string | No | Optional free-text note stating, in one short sentence, why you are calling this tool. It does not affect the result and is recorded only for diagnostics. This tool takes no other input: do not put data, filters, or parameters here, and omit it entirely if you have nothing to say. Do not include personal or financial details. | ### Referral join referral program **Slug:** `ERA_CONTEXT_MCP_REFERRAL__JOIN_REFERRAL_PROGRAM` 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. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `reason` | string | No | Optional free-text note stating, in one short sentence, why you are calling this tool. It does not affect the result and is recorded only for diagnostics. This tool takes no other input: do not put data, filters, or parameters here, and omit it entirely if you have nothing to say. Do not include personal or financial details. | ### Referral switch referral campaign **Slug:** `ERA_CONTEXT_MCP_REFERRAL__SWITCH_REFERRAL_CAMPAIGN` 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. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `slug` | string | Yes | The campaign slug to switch to. Valid values: 'friends-family-usd' (fixed reward per referred friend, paid in the user's own billing currency) or 'creator' (30% recurring commission for 12 months). | ### Transactions import csv transactions **Slug:** `ERA_CONTEXT_MCP_TRANSACTIONS__IMPORT_CSV_TRANSACTIONS` 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. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `format` | string ("monarch" | "copilot" | "ynab" | "mint" | "wellsfargo" | "chase" | "bankofamerica" | "amex" | "schwab") | No | Optional format hint to bypass auto-detection. Supported values: "monarch", "copilot", "ynab", "mint", "wellsfargo", "chase", "bankofamerica", "amex", "schwab". If omitted, format is auto-detected from the CSV header row. | | `csv_content` | string | Yes | The complete CSV text content (including header row). Pass the raw CSV as a string — do NOT base64-encode, MCP is text-native. | | `preview_only` | string | No | When true, parse and validate the CSV but do not write transactions. Returns per-row validation verdicts (valid/invalid + reason). Default: false. | | `account_group_key` | string | Yes | The account group projection key of the manual account to import into. Obtain from accounts__list_financial_accounts (the account_id field). Must be a manual account. | ### Transactions list recurring charges **Slug:** `ERA_CONTEXT_MCP_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. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `type` | string ("all" | "subscription" | "bill" | "income") | No | Filter by type: 'subscription' (Netflix, Spotify, etc.), 'bill' (rent, utilities, etc.), 'income' (salary, freelance, etc.), or 'all' for everything. | | `active_only` | string | No | When true (default), only shows recurring items that have appeared within the last 60 days. Set to false to also include items that may have stopped. | ### Transactions list spending categories **Slug:** `ERA_CONTEXT_MCP_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. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `reason` | string | No | Optional free-text note stating, in one short sentence, why you are calling this tool. It does not affect the result and is recorded only for diagnostics. This tool takes no other input: do not put data, filters, or parameters here, and omit it entirely if you have nothing to say. Do not include personal or financial details. | ### Transactions list transactions **Slug:** `ERA_CONTEXT_MCP_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. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `page` | string | No | Page number (1-based) | | `to_date` | string | No | End date for transaction range (YYYY-MM-DD). Defaults to today. Format: yyyy-MM-dd. | | `rule_ids` | string | No | Rule projection keys (e.g. ["frul_abc"]). Only transactions matched by at least one of these rules are returned. Maximum 50 items; requests with more than 50 items are rejected with an error. Get rule keys from transactions__manage_automation_rules with 'list' action. | | `tag_keys` | string | No | Tag projection keys (e.g. ["ftag_abc"]). Only transactions with at least one of these tags are returned. Maximum 50 items; requests with more than 50 items are rejected with an error. Get tag keys from transactions__manage_transaction_tags with 'list_tags' action. | | `from_date` | string | No | Start date for transaction range (YYYY-MM-DD). Defaults to the earliest transaction history the caller's plan permits — see the tool description for the free-plan history window. Format: yyyy-MM-dd. | | `page_size` | string | No | Number of transactions per page (max 100) | | `category_key` | string | No | Filter to transactions with this fcat_* category projection key. Get category keys from transactions__list_spending_categories. When combined with include_children=true, includes transactions from all subcategories. | | `review_status` | string ("needs_review" | "reviewed" | "flagged") | No | Filter to transactions by their review status. System rules like anomaly detection and bounced payment detection automatically flag transactions as 'needs_review'. | | `include_pending` | string | No | When true, also return pending (authorization-hold) transactions dated within the recent-pending window described in the tool description, each with is_pending=true. Default false. Pending rows are read-only. | | `include_children` | string | No | When true and category_key is set, includes transactions from the parent category and all its subcategories. Use this for parent category transaction counts. | | `account_group_key` | string | No | Filter to transactions from a specific account. Pass the account group projection key from accounts__list_financial_accounts (the account_group_key field). | ### Transactions manage automation rules **Slug:** `ERA_CONTEXT_MCP_TRANSACTIONS__MANAGE_AUTOMATION_RULES` 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. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `action` | string ("create" | "list" | "update" | "delete" | "enable" | "disable" | "preview") | Yes | What to do. Create adds a new rule, list shows existing rules, update changes a rule's conditions or actions, delete removes a rule permanently, enable/disable turns a rule on or off without deleting it, preview tests filters against recent transactions without saving anything. | | `actions` | string | No | What to do with matching transactions (required for create and update). You can combine multiple actions. For category, merchant rename, description, review status, hide, and transfer actions, only the highest-priority rule's action applies. Tag actions (add/remove) always apply from all matching rules. | | `filters` | string | No | Conditions that determine which transactions this rule matches (required for create and update). When multiple filters are provided at the top level, ALL must match (AND logic). Use 'or' type filters to match ANY of several conditions. | | `version` | string | No | The current version number of the rule, used to prevent conflicting edits. REQUIRED for update, delete, enable, and disable. Get this value from the 'list' action response. If someone else changed the rule since you last read it, the operation will fail with a conflict error — re-read the rule and retry. | | `priority` | string | No | Rules with higher priority numbers are evaluated first. When two rules could both set a category (or merchant name, etc.) on the same transaction, the higher-priority rule wins. Default: 0. | | `rule_key` | string | No | The unique key of an existing rule. Required for update, delete, enable, and disable. Get this from the 'list' action response. | | `rule_name` | string | No | A short, descriptive name for the rule (e.g., 'Categorize Uber as Transportation'). Required for create and update. | | `applies_to` | string | No | Only apply this rule to transactions dated on or before this date (YYYY-MM-DD). Omit to apply to transactions of any date. Format: yyyy-MM-dd. | | `rule_scope` | string ("transaction" | "pattern") | No | The rule scope: 'transaction' (default) evaluates filters against each individual transaction. 'pattern' evaluates a pattern specification against a time-windowed batch of transactions. | | `description` | string | No | An optional note explaining what this rule does or why it was created. | | `window_days` | string | No | How many days to look back when searching for matching patterns. Required for pattern-scope rules. Must be between 1 and 365. | | `applies_from` | string | No | Only apply this rule to transactions dated on or after this date (YYYY-MM-DD). Omit to apply to transactions of any date. Format: yyyy-MM-dd. | | `pattern_spec` | string | No | The pattern detection specification. Required for pattern-scope rules. Supports four types: pair_match (transfer detection between accounts), frequency_threshold (counting occurrences in a window), recurring_group (periodic merchant charge detection), and statistical_anomaly (z-score anomaly detection). | | `trigger_mode` | string ("on_each_transaction" | "on_batch_complete" | "on_schedule" | "on_demand") | No | When to trigger pattern evaluation. Defaults to 'on_batch_complete' for pattern rules, 'on_each_transaction' for transaction rules. | | `user_overrides` | string | No | Optional overrides for library rule parameters. Must match the rule's pattern_spec type (e.g. pair_match overrides for a pair_match rule). Library rules cannot be created or deleted, but their behavior can be customized using this field on update. | | `include_inactive` | string | No | When listing rules, set to true to also include disabled rules. Default: false (only active rules are shown). | | `application_scope` | string ("prospective" | "retroactive" | "both") | No | Determines which transactions this rule applies to. Prospective applies only to new transactions going forward. Retroactive applies only when explicitly re-running against existing transactions. Both (default) does both. | | `apply_retroactively` | string | No | Whether to immediately apply the rule to the user's existing transactions. Default: true — all matching transactions are updated right away. When updating an existing rule, the old matches are undone first and the new definition is applied fresh. Set to false only if the user explicitly asks for the rule to apply to future transactions only. | | `revert_retroactively` | string | No | When deleting or disabling a rule, whether to undo the changes it previously made to transactions (e.g., remove the category it assigned, remove tags it added). Default: false — previous changes are left in place. Set to true for a clean undo so the user's transactions return to their state before the rule existed. | | `window_lookahead_days` | string | No | How many days to look ahead when searching for matching patterns. Default: 0 (no lookahead). | | `window_exclude_trigger_account` | string | No | When true, transactions from the same account as the trigger are excluded from the window query. Useful for transfer detection to avoid self-matching. | ### Transactions manage categories **Slug:** `ERA_CONTEXT_MCP_TRANSACTIONS__MANAGE_CATEGORIES` 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. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `name` | string | No | The display name for the category. Required for create, optional for update (null = unchanged). | | `slug` | string | No | A unique URL-safe slug for the new category (lowercase alphanumeric and hyphens, 2-50 chars). Required for create. | | `action` | string ("create" | "update" | "hide" | "unhide" | "delete" | "merge_categories" | "reorder" | "reset") | Yes | What to do. Create adds a new custom category, update changes display properties, hide/unhide controls visibility, delete removes a user-created category, merge_categories combines multiple into one. | | `icon_name` | string | No | A single UTF emoji character used as the category icon in the UI (e.g. "🏠", "💰"). Optional. | | `description` | string | No | A description of what this category covers. Optional. | | `category_key` | string | No | The category key to operate on. Required for update, hide, unhide, delete. For merge_categories this is the target category key. | | `display_order` | string | No | Display order within sibling group. Optional. | | `spending_type` | string ("necessary" | "discretionary" | "income" | "savings" | "transfer" | "other") | No | Spending classification for budgeting and analytics. Optional. | | `reorder_entries` | string | No | List of {category_key, display_order} pairs. Required for reorder. | | `merge_source_keys` | string | No | Category keys to merge into the target. Required for merge_categories. These categories will be hidden. | | `source_system_keys` | string | No | System category keys (fcat_*) whose transactions should be routed to this new category. Used with create and merge_categories. Each source gets a mapping rule. | | `apply_retroactively` | string | No | When true, retroactively re-evaluates transactions (up to 12 months) after mapping rules are created. Defaults to true. | | `parent_category_key` | string | No | The parent category key (fcat_*) under which to create the new category. Required for create. | | `assignment_eligibility` | string ("agent_eligible" | "manual_only") | No | Controls whether the AI agent can auto-assign transactions to this category. Optional. | ### Transactions manage manual transaction **Slug:** `ERA_CONTEXT_MCP_TRANSACTIONS__MANAGE_MANUAL_TRANSACTION` 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. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `operations` | array | Yes | Array of transaction operations to execute sequentially. Each has its own action and fields. | | `preview_only` | string | No | When true, parse and validate all operations but do not write anything. Returns per-operation validation verdicts (valid/invalid + reason) for every operation the request carries, provided the request itself is readable: a value that is malformed for its declared type is rejected before any operation is examined, and that call returns one error naming the operation index rather than a set of verdicts. Default: false. | | `account_group_key` | string | Yes | The account group projection key shared by all operations. Obtain from accounts__list_financial_accounts (the account_id field). Must be a manual account. | ### Transactions manage transaction tags **Slug:** `ERA_CONTEXT_MCP_TRANSACTIONS__MANAGE_TRANSACTION_TAGS` 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. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `icon` | string | No | An icon name for the tag's visual appearance. Optional. | | `name` | string | No | The tag name (required for create_tag). Spaces are replaced with hyphens and text is lowercased to create a stable identifier (e.g., 'Business Trip' becomes 'business-trip'). Maximum 50 characters. | | `color` | string | No | A hex color code for the tag's visual appearance (e.g., '#FF5733'). Optional. | | `action` | string ("create_tag" | "list_tags" | "get_tag" | "update_tag" | "delete_tag" | "assign_tags" | "remove_tags") | Yes | What to do: 'create_tag' makes a new tag, 'list_tags' shows all tags, 'get_tag' gets details for one tag, 'update_tag' changes a tag's name or appearance, 'delete_tag' removes a tag, 'assign_tags' attaches a tag to specific transactions, 'remove_tags' detaches a tag from specific transactions. | | `tag_key` | string | No | The tag's unique identifier (required for get_tag, update_tag, delete_tag, assign_tags, remove_tags). Get this from create_tag or list_tags responses. | | `version` | string | No | The current version number of the tag, used to prevent conflicting edits. REQUIRED for update_tag and delete_tag. Get this from list_tags or get_tag responses. | | `tag_type` | string ("user" | "auto") | No | Whether this tag was created by the user ('user', default) or by an automation rule ('auto'). | | `type_filter` | string ("user" | "system" | "auto") | No | When listing tags, only show tags of this type. Optional. | | `display_name` | string | No | The name shown to the user (e.g., 'Business Trip'). Optional when creating (defaults to the tag name). Required when updating. Maximum 50 characters. | | `include_deleted` | string | No | When listing tags, set to true to also include previously deleted tags. Default: false. | | `transaction_ids` | string | No | The transaction group IDs (utgr_*) to tag or untag. REQUIRED for assign_tags and remove_tags. Get these from transactions__list_transactions or transactions__search_transactions responses. Up to 100 per call. | ### Transactions manage transfer links **Slug:** `ERA_CONTEXT_MCP_TRANSACTIONS__MANAGE_TRANSFER_LINKS` 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. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `action` | string ("list" | "confirm" | "reject") | Yes | What to do: 'list' shows detected transfer links between accounts, 'confirm' marks a detected transfer as confirmed by the user (upgrades confidence), 'reject' removes a false positive transfer link and prevents re-detection. | | `transaction_id` | string | No | When listing, only show transfer links involving this specific transaction. Optional. | | `transfer_link_id` | string | No | The unique identifier of the transfer link to confirm or reject. Get this from the 'list' action response. Required for confirm and reject. | ### Transactions search transactions **Slug:** `ERA_CONTEXT_MCP_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. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `limit` | string | No | Maximum number of transactions to return (1-50). The response also includes total_results count and sum even if the limit clips the list. | | `query` | string | No | Free-text search across merchant name and description. Exact merchant names are not required — partial matches work (e.g., 'star' matches 'Starbucks'). | | `period` | string ("this_week" | "this_month" | "last_month" | "last_7_days" | "last_30_days" | "last_90_days" | "this_year" | "last_year" | "custom" | "all_time") | No | Time range to search within. Use 'custom' with period_start/period_end for a specific date range. | | `sort_by` | string ("date" | "amount" | "merchant") | No | How to order the results: by 'date' (newest first), 'amount', or 'merchant' name. | | `rule_ids` | string | No | Rule projection keys (e.g. ["frul_abc"]). Only transactions matched by at least one of these rules are returned. Maximum 50 items; requests with more than 50 items are rejected with an error. Get rule keys from transactions__manage_automation_rules with 'list' action. | | `tag_keys` | string | No | Tag projection keys (e.g. ["ftag_abc"]). Only transactions with at least one of these tags are returned. Maximum 50 items; requests with more than 50 items are rejected with an error. Get tag keys from transactions__manage_transaction_tags with 'list_tags' action. | | `direction` | string ("all" | "debit" | "credit") | No | Filter by money direction: 'debit' for money going out (purchases, payments), 'credit' for money coming in (income, refunds), or 'all' for both. | | `max_amount` | string | No | Maximum transaction amount. | | `min_amount` | string | No | Minimum transaction amount. Use negative values for charges/debits (e.g., -100 finds charges of $100 or more). | | `period_end` | string | No | Custom end date (YYYY-MM-DD). Used when period is 'custom'. Format: yyyy-MM-dd. | | `category_key` | string | No | Filter to transactions with this fcat_* category projection key. Get category keys from transactions__list_spending_categories. When combined with include_children=true, includes transactions from all subcategories. | | `period_start` | string | No | Custom start date (YYYY-MM-DD). Used when period is 'custom'. Format: yyyy-MM-dd. | | `review_status` | string ("needs_review" | "reviewed" | "flagged") | No | Filter to transactions by their review status. System rules like anomaly detection and bounced payment detection automatically flag transactions as 'needs_review'. | | `include_pending` | string | No | When true, also return pending (authorization-hold) transactions dated within the recent-pending window described in the tool description, each with is_pending=true. Default false. Pending rows are read-only. | | `include_children` | string | No | When true and category_key is set, includes transactions from the parent category and all its subcategories. Use this for parent category transaction counts. | | `account_group_key` | string | No | Filter to transactions from a specific account. Pass the account group projection key from accounts__list_financial_accounts (the account_group_key field). | ### Transactions update transactions **Slug:** `ERA_CONTEXT_MCP_TRANSACTIONS__UPDATE_TRANSACTIONS` 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. #### Input Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `description` | string | No | Set a custom note or description for these transactions. | | `category_key` | string | No | The category to assign to these transactions. Call transactions__list_spending_categories first to get valid category keys. | | `merchant_name` | string | No | Set a custom merchant name for these transactions (e.g., rename 'AMZN*1234' to 'Amazon'). | | `review_status` | string ("needs_review" | "reviewed" | "flagged") | No | Review status to assign: needs_review, reviewed, or flagged. | | `clear_category` | string | No | Remove the user's manual category choice, reverting to the automatically detected category. | | `transaction_ids` | array | Yes | IDs of the transactions to update (up to 100 at once). Get these from transactions__list_transactions or transactions__search_transactions. | | `clear_description` | string | No | Remove the user's custom description, reverting to the original description from the bank. | | `clear_merchant_name` | string | No | Remove the user's custom merchant name, reverting to the original name from the bank. | | `clear_review_status` | string | No | Clear the review status. Use this instead of review_status when removing a status. |