Personal finance for AI agents: accounts, budgets, goals, 9-strategy debt payoff, reports. OAuth 2.1
Scored across 179 tools
Most tools are distinguishable by resource+action, but the analytics surface overlaps heavily: get_net_worth vs get_balance_sheet vs get_financial_ratios vs get_financial_health_score, and get_cash_flow vs forecast_cash_flow vs get_period_summary vs get_savings_rate_trend have subtle boundaries. get_debt_paydown vs get_standing_facts and get_goal_plan vs get_goal_projection further rely on long descriptions so an agent must read carefully to pick correctly.
The set consistently uses snake_case verb_noun names (list_, get_, create_, update_, delete_, plus specific verbs like bulk_, forecast_, import_, export_); no camelCase or mixed styles. The verb inventory sprawls with near-synonyms (accept/confirm/apply, get/list, sync/unlink), making it slightly less predictable than a strict pattern.
179 tools is an extreme mismatch for a coherent MCP surface; even a broad personal-finance domain shouldn't require this many. The count makes discovery, selection, and context budget impractical, spamming the agent with forum, billing, gamification, family, and analytics tools it rarely needs.
Coverage is broad: full CRUD for accounts, transactions, budgets, categories, tags, goals, milestones, recurring templates, scenarios, and family/forum/support flows, plus Plaid sync, imports/exports, and extensive analytics. Minor gaps exist, like no transaction splitting/merging, no category merge, no forum category management, and no undo for scenario commit.
Accept a pending family invitation.
Args:
invitation_id: ID of the invitation to accept
Returns:
Confirmation with group details.
Inputs: invitation_id (required).
Accept Plaid's current balance as correct, clearing any mismatch warning.
This doesn't change the balance value (unlike a balance override)
— it just acknowledges the current balance is accurate and removes the
warning flag on the account. Plaid-linked accounts only.
Args:
account_id: The Plaid-linked account
Returns:
Updated account snapshot
Inputs: account_id (required).
Activate a color theme.
Args:
theme_id: Theme identifier (light, dark, emerald_banking, frost_glass, carbon)
Returns:
Confirmation with the activated theme
Inputs: theme_id (required).
Apply user-confirmed statement fields to one of the user's accounts.
Premium-only. Only the fields passed are written; each is re-validated
server-side (same bounds as the web + REST paths) under a row lock.
Args:
account_id: The account to update (the caller's own, active).
balance: New balance.
interest_rate: APR percent, 0-100, up to 3 decimals.
credit_limit: Credit limit (>= 0).
minimum_payment: Minimum payment (>= 0).
institution: Institution name (max 200 chars).
original_balance: Original loan/balance amount (>= 0).
term_months: Loan term in months (1-600).
loan_start_date: Loan start date, YYYY-MM-DD.
loan_end_date: Loan maturity/payoff date, YYYY-MM-DD.
Returns:
``{"success": True, "account_id": ..., "updated_fields": [...],
"new_balance": ...}`` on success, or ``{"error": "..."}`` (not
Premium, account not found, bad value, or nothing to apply).
Inputs: account_id (required), balance, institution, term_months, +6 more.
Assign a category to multiple transactions at once.
Args:
transaction_ids: List of transaction IDs to categorize
category_name: Category name to assign (case-insensitive)
Returns:
Count of updated transactions.
Inputs: category_name (required), transaction_ids (required).
Delete multiple transactions at once with per-row rule-21 semantics.
Each row gets the same treatment as a single-transaction delete:
manual transactions are soft-deleted (balance reversed, restorable
for 7 days); Plaid-originated transactions
are hard-deleted (restoring them after Plaid has moved on creates
ledger drift). Future-dated (unapplied) rows skip balance reversal.
IDs that are missing or belong to another user are skipped and
reported; those rows are left untouched.
Args:
transaction_ids: List of transaction IDs to delete (max 100)
Returns:
Per-id results with `undoable` flags, counts, and a note about
the 7-day undo window for soft-deleted rows.
Inputs: transaction_ids (required).
Cancel the user's paid subscription. Premium access continues
until the end of the current billing period.
Returns ``{"success": True, ...}`` or ``{"error": ...}``.
No-op for users on Free, family-shared, or trialing-without-card.
Inputs: no named parameters.
Will upcoming scheduled payments clear? Per-account coverage projection.
For every bill-paying account: the known scheduled payments in the
window (recurring templates — including a brand-new template's first
occurrence — plus Plaid debt due dates), scheduled deposits
(paychecks), a date-ordered projected-balance timeline, the projected
minimum balance, and a status per account:
- ``ok`` — everything clears with cushion to spare
- ``below_threshold`` — clears, but dips under the account's
low-balance cushion (``cushion_shortfall`` says by how much)
- ``overdraft_risk`` — projected NEGATIVE (``overdraft_shortfall``
is the amount needed to cover)
Answers questions like "will I have enough when X hits?", and shows
whether a new recurring withdrawal or scheduled payment would clear.
Shortfall entries carry the amount and the date of the low point.
Covering a shortfall (e.g. a transfer from savings) happens at the
user's bank; Zoninga moves no money.
``unattributed_bills`` are Plaid debt-account due dates that can't be
tied to a specific funding account; they are measured against
``checking_total_balance`` rather than any single account.
Args:
days: look-ahead window in days (default 14, max 90)
Returns:
Per-account coverage entries + overall_status + a summary line.
Inputs: days.
Commit a scenario — create its add items as real accounts.
Turns the scenario's add-debt / add-asset changes into real Account
rows and archives any sell/remove targets. Use ONLY after confirming
with the user that they've actually gone through with the change and
the numbers are still correct. Enforces the account limit.
Args:
scenario_id: The scenario to commit.
Returns:
{"success": True, "created_accounts": [{id, name}], "scenario": {...}}
or {"error": "..."}.
Inputs: scenario_id (required).
Confirm a pending debt payment match — creates the corresponding
debt-account transaction, increments the rule's confirmed_count, and
auto-enables the rule once the threshold (default 2) is reached.
Args:
debt_payment_id: ID of the pending DebtPayment record to confirm
Returns:
Updated debt payment details
Inputs: debt_payment_id (required).
Add a contribution to a financial goal.
Args:
goal_id: The goal ID to contribute to
amount: Contribution amount (positive number)
note: Optional note for this contribution
Returns:
Updated goal details
Inputs: amount (required), goal_id (required), note.
Create a new financial account.
Args:
name: Account name (e.g., "Chase Checking", "Visa Credit Card")
account_type: One of: checking, savings, cash, credit_card, loan, mortgage,
student_loan, heloc, arm, investment, other_asset, other_debt
balance: Opening balance (default: 0.00, can be negative for debt accounts)
institution: Bank or financial institution name
institution_login_url: Where the user logs in at this institution
(https only, e.g. "https://chase.com"; bare domains are
normalized to https). Optional; intended for a URL the user
provided, not a guessed or invented one. Plaid-linked accounts
get one automatically.
currency: Currency code. App is locked to USD pre-launch — any other
value is rejected. (See docs/CURRENCY_RESTORE_TODO.md to re-enable
multi-currency.)
interest_rate: Annual interest rate as percentage (0-100). For HELOC, this
is the draw-phase rate. For ARM, this is the initial fixed rate.
credit_limit: Credit limit (for credit card accounts)
minimum_payment: Minimum monthly payment (for debt accounts)
term_months: Original loan term in months (e.g. 360 for a 30-year mortgage)
loan_start_date: Loan origination date (YYYY-MM-DD)
loan_end_date: Loan payoff target date (YYYY-MM-DD)
original_balance: Original loan/debt amount when first taken out
monthly_escrow_tax: Monthly property-tax escrow (mortgage only)
monthly_escrow_insurance: Monthly insurance escrow (mortgage only)
draw_period_months: Number of months in the HELOC draw-down phase
draw_amount_per_month: Monthly draw amount during HELOC draw-down phase
rate_2: 2nd-term annual interest rate as percentage — HELOC repayment
rate or ARM adjusted rate
term_2_months: 2nd-term duration in months — HELOC repayment term or
ARM remaining term after the adjustment
arm_initial_period_months: Fixed-rate period in months before ARM
adjustment (e.g. 60 for a 5/1 ARM)
include_in_debt_paydown: Whether this debt is part of the payoff
calculator and the dashboard payoff card (default True). Set
False for a debt you pay in full every month (e.g. a credit
card that carries no balance month to month) so it doesn't distort the
plan. Ignored for asset accounts; does NOT affect net worth,
total debt, or the balance sheet.
low_balance_alert_threshold: Per-account low-balance alert
threshold in dollars (checking/savings/cash only). Omit to use
the monitoring plan's global threshold.
mute_low_balance_alerts: Suppress low-balance alerts on this account
(daily brief + notifications). For accounts the user
intentionally keeps low. Default False.
Returns:
Created account details
Inputs: name (required), account_type (required), rate_2, balance, +19 more.
Create a new budget for an expense category.
Args:
category_name: Name of the expense category to budget (case-insensitive)
amount: Monthly/yearly budget amount (minimum: 0.01)
period: Budget period - "monthly" or "yearly" (default: monthly)
start_date: Start date in YYYY-MM-DD format (defaults to 1st of current month)
rollover: Carry unspent budget to next period (monthly budgets only, default: False)
name: Optional display name. Defaults to the category name when blank. Useful
when a user wants multiple visibly-distinct budgets without duplicating
the category itself (Phase 92 #K1).
Returns:
Created budget details
Inputs: amount (required), category_name (required), name, period, +2 more.
Create a new custom category.
Args:
name: Category name (max 50 chars)
category_type: "income" or "expense" (default: expense)
Returns:
Created category details
Inputs: name (required), category_type.
Create a rule that auto-matches withdrawals on an asset account to a debt account.
When a transaction on `source_account_id` has a description containing
the `description_pattern` (case-insensitive substring), the system
creates a pending debt payment that the user can confirm or reject.
After the configured threshold of confirmations, matches auto-apply.
Args:
source_account_id: Asset account the payment leaves from (e.g. checking)
debt_account_id: Debt account the payment reduces (e.g. mortgage)
description_pattern: Substring to match on the source transaction (<=200 chars)
Returns:
Created or reactivated rule details
Inputs: debt_account_id (required), source_account_id (required), description_pattern (required).
Create a new family group (user becomes owner). Requires Premium.
Args:
name: Group name
Returns:
Created group details
Inputs: name (required).
Create a new forum post.
Args:
category_slug: Slug of the category to post in
title: Post title (3-200 chars)
content: Raw markdown content (10-10000 chars)
Returns:
``{"success": True, "post": {...}}`` on success, or
``{"error": "..."}`` (unknown category, validation, or a staff-only
category for a non-staff user).
Inputs: title (required), content (required), category_slug (required).
Reply to a forum post.
Args:
post_id: The parent post ID
content: Raw markdown content (5-10000 chars)
Returns:
``{"success": True, "reply": {...}}`` on success, or
``{"error": "..."}`` (post not found, locked, or validation).
Inputs: content (required), post_id (required).
Create a new financial goal.
Args:
name: Goal name (e.g., "Emergency Fund", "Vacation to Italy")
target_amount: Target amount to save (minimum: 0.01)
goal_type: One of: savings, debt_payoff, emergency_fund, custom (default: savings)
target_date: Target date in YYYY-MM-DD format (optional)
current_amount: Starting amount already saved (default: 0, ignored if linked_account)
linked_account_id: Link to an existing account for auto-tracking (optional)
color: Hex color code for the goal (default: #007bff)
notes: Optional notes about the goal
priority: Priority level (0 = highest, default: 0)
vng_goal_id: Optional Visions & Goals plan id to link (the
qualitative clarify-and-plan companion at visionsandgoals.com)
Returns:
Created goal details with progress
Inputs: name (required), target_amount (required), color, notes, +6 more.
Create a goal PLAN on Visions & Goals — the qualitative
clarify-and-plan side (SMART criteria, action steps). Suited to a
vague aspiration that needs shaping ("I want to get fit", "someday
buy a cabin"). The money-tracking side is a separate zoninga goal;
the two can be linked.
Args:
title: The goal statement (required, ≤300 chars).
description: Longer context for the plan.
timeframe: One of "short", "medium", "long" (default medium).
target_date: YYYY-MM-DD (optional).
smart_specific: Answer to the SMART "Specific" prompt (optional).
smart_measurable: SMART "Measurable" answer (optional).
smart_achievable: SMART "Achievable" answer (optional).
smart_relevant: SMART "Relevant" answer (optional).
smart_timebound: SMART "Time-bound" answer (optional).
zoninga_goal_id: An existing zoninga goal id to link the new
plan to (sets that goal's ``vng_goal_id``).
Returns:
{"goal": {id, title, ..., edit_url}}. ``edit_url`` is the page
on Visions & Goals where the plan can be refined.
Inputs: title (required), timeframe, description, target_date, +6 more.
Create a hard asset (real estate, vehicle, valuable) for net worth tracking.
Args:
name: Asset name (e.g., '123 Main St', '2022 Toyota Camry')
category: One of: real_estate, vehicle, jewelry, art, electronics, furniture, other
current_value: Current estimated value
purchase_price: Original purchase price (optional)
purchase_date: Purchase date in YYYY-MM-DD format (optional)
description: Description or notes (optional)
location: Physical location (optional)
linked_account_id: Associated debt account ID, e.g., mortgage (optional)
Returns:
Created hard asset details.
Inputs: name (required), category (required), current_value (required), location, +4 more.
Create a milestone checkpoint within a goal.
Args:
goal_id: The parent goal ID
name: Short milestone name ("25% saved", "First $1k")
target_amount: Amount at which the milestone is reached (> 0 and <= goal target)
celebration_message: Optional message shown when reached
Returns:
Created milestone details
Inputs: name (required), goal_id (required), target_amount (required), celebration_message.
Create a recurring transaction template.
Args:
account_id: Source account
amount: Positive decimal in major units
description: Free-text description
frequency: One of daily, weekly, bi_weekly, monthly, yearly
start_date: ISO date (YYYY-MM-DD); first instance will spawn on this date
transaction_type: deposit | withdrawal | transfer (default: withdrawal)
category_id: Optional Category id
end_date: Optional ISO date when the recurrence stops
transfer_to_account_id: Required when transaction_type=transfer
Returns:
The created template (or ``{"error": ...}`` on validation failure).
Inputs: amount (required), frequency (required), account_id (required), start_date (required), +5 more.
Schedule a reminder for the user. It appears in their morning brief on
matching days ("Reminder: <text>"), and in the brief email when they
have daily-brief email delivery turned on. This is the right tool for
asks like "remind me every other Friday to pay child support".
Args:
text: What to remind them of (max 200 chars), e.g. "pay child support".
frequency: once / weekly / biweekly / monthly / yearly. weekly and
biweekly repeat on start_date's weekday; monthly repeats on its
day-of-month (clamped in short months); yearly repeats on its
month + day (e.g. a birthday).
start_date: First occurrence, YYYY-MM-DD.
end_date: Optional last day (YYYY-MM-DD) after which it stops.
Returns:
{"success": True, "reminder": {...}, "delivery_note"?: str}. Relay
delivery_note to the user when present — it means the brief cadence
won't actually deliver the reminder (plan inactive / cadence off or
non-daily).
Inputs: text (required), frequency (required), start_date (required), end_date.
Create a what-if scenario and return its projected impact.
A scenario bundles one or more hypothetical changes (buy a car, take a
mortgage, open a credit card, sell the house). It auto-saves for 60
days; committing it later turns its add items into real accounts.
Each item is a dict:
- add_debt: {action:"add_debt", account_type (credit_card / loan /
mortgage / student_loan / heloc / arm / other_debt), name, balance,
interest_rate, minimum_payment, term_months; for HELOC/ARM also the
full two-phase set rate_2 + term_2_months + draw_period_months or
arm_initial_period_months}
- add_asset: {action:"add_asset", account_type (cash / checking /
savings / investment / other_asset), name, balance}
- remove: {action:"remove", target_account_id} — sells/drops an
existing account from the projection.
Args:
name: Short label for the scenario (e.g. "Buy a 2026 Honda").
items: List of change dicts (see shapes above).
description: Optional notes.
strategy: Paydown strategy for the projection (default highest_rate
/ avalanche).
extra_monthly: Extra monthly payment applied to the projection.
Returns:
{scenario: {...}, analysis: {...}} or {"error": "..."}.
Inputs: name (required), items (required), strategy, description, +1 more.
Create a personal spending challenge.
Args:
name: Challenge name (e.g., "No Coffee November")
category_name: Category to track (e.g., "Dining", "Entertainment")
metric: "spending_limit" (stay under target) or "spending_avoidance" (spend $0)
target_amount: Target amount (used for spending_limit; set 0 for avoidance)
duration_days: Duration in days (7 or 30)
Returns:
Created challenge details
Inputs: name (required), metric (required), category_name (required), target_amount (required), +1 more.
File a new support ticket on the user's behalf.
Writes to Zoninga's own support desk (no third-party service). Staff
handle the ticket on the web support hub and the user is notified of
replies. API docs: https://zoninga.com/ai/#support-tickets
Args:
subject: Short summary (1-200 chars).
body: The full message describing the issue (1-5000 chars).
category: One of ``bug``, ``feature``, ``billing``, ``account``,
``other`` (default ``other`` — staff re-triage anyway).
Priority is NOT settable here — staff triage urgency.
Returns:
``{"success": True, "ticket": {...}}`` (the new ticket, with its
initial message counted), or ``{"error": "..."}`` on validation
failure.
Inputs: body (required), subject (required), category.
Create a tag.
Args:
name: Tag name (max 30 chars), unique per user.
color: Hex color code like ``#007bff`` (default: gray)
Inputs: name (required), color.
Create a new transaction.
Args:
account_id: The account ID for this transaction
amount: Transaction amount (positive number)
description: Description of the transaction
transaction_type: 'deposit', 'withdrawal', or 'transfer'.
On asset accounts (checking, savings, cash, investment):
- 'deposit' = money in (pair with an income category like "Salary")
- 'withdrawal' = money out (pair with an expense category like "Groceries")
On debt accounts (credit_card, loan, mortgage, heloc, arm, student_loan):
- 'deposit' = a charge/purchase that INCREASES the debt
(pair with an expense category like "Shopping")
- 'withdrawal' = a payment that DECREASES the debt
(pair with an income category like "Credit Card Payment")
Record a CC purchase as transaction_type='deposit' with an expense
category; record a CC bill payment as transaction_type='withdrawal'
with an income category. The category type is inverted on debt
accounts versus asset accounts — this is by design.
transaction_date: Date in YYYY-MM-DD format (defaults to current UTC date)
category_name: Category name (optional, case-insensitive)
transfer_to_account_id: Destination account ID (required for transfers)
confirm_future: If transaction_date is more than 30 days in the
future, the tool refuses and returns a `requires_confirmation`
error. Resubmit with confirm_future=True to accept — e.g.
scheduled rent a few months out. Defaults to False to catch
fat-fingered dates like "2035-01-01".
Returns:
Created transaction details
Inputs: amount (required), account_id (required), description (required), transaction_type (required), +4 more.
Decline a pending family invitation.
Args:
invitation_id: ID of the invitation to decline
Returns:
Confirmation.
Inputs: invitation_id (required).
Delete (soft-delete) a financial account. The account is deactivated, not permanently removed.
Args:
account_id: The account ID to delete
Returns:
Confirmation of deletion
Inputs: account_id (required).
Delete one of the user's AI assistant chat sessions, including
every message in it.
This is irreversible — the cron-driven 90-day retention sweep
does the same thing for old sessions, but this tool is for users
who want to clear a session immediately (e.g. they shared
context they no longer want stored). The persistent main
conversation thread can't be deleted.
Args:
session_id: The chat session's ID.
Returns:
``{"success": True, "deleted_session_id": ..., "deleted_messages": N}``
or ``{"error": "..."}``.
Inputs: session_id (required).
Delete a budget (soft delete).
Args:
budget_id: The ID of the budget to delete
Returns:
Confirmation of deletion
Inputs: budget_id (required).
Delete a user-created category. System categories cannot be deleted.
Args:
category_id: The category ID to delete
Returns:
Confirmation of deletion
Inputs: category_id (required).
Deactivate a debt payment rule (soft delete).
Existing DebtPayment records created by the rule are retained for audit.
Args:
rule_id: ID of the rule to deactivate
Returns:
Confirmation of deactivation
Inputs: rule_id (required).
Delete a family chat message. Users can delete their own messages at
any time; group owners and admins can delete anyone's messages.
Args:
message_id: ID of the message to delete
Returns:
Confirmation on success, or error dict
Inputs: message_id (required).
Delete a forum post (author or staff). Replies cascade.
Args:
post_id: The post to delete.
Returns:
``{"success": True, "deleted_post_id": post_id}`` on success, or
``{"error": "..."}`` (not found, or not author/staff).
Inputs: post_id (required).
Delete a forum reply (author or staff).
Args:
reply_id: The reply to delete.
Returns:
``{"success": True, "deleted_reply_id": reply_id}`` on success, or
``{"error": "..."}`` (not found, or not author/staff).
Inputs: reply_id (required).
Cancel a financial goal (soft delete).
Args:
goal_id: The ID of the goal to cancel
Returns:
Confirmation of cancellation
Inputs: goal_id (required).
Delete a hard asset (soft-deactivate).
Args:
asset_id: ID of the hard asset to delete
Returns:
Confirmation message.
Inputs: asset_id (required).
Delete a milestone. (Milestones are hard-deleted — they're not user-facing records.)
Args:
milestone_id: The milestone ID to delete
Returns:
Confirmation of deletion
Inputs: milestone_id (required).
Permanently delete a notification from the user's inbox.
Deletion removes the notification from the user's history entirely
(e.g. dismissing an old Weekly Recap row); marking it read is the
non-destructive way to clear an unread badge.
Args:
notification_id: ID of the notification to delete.
Returns:
{"success": True, "deleted_id": ...} on success,
{"error": "..."} if the notification doesn't exist or isn't
owned by the caller.
Inputs: notification_id (required).
Delete one of the user's saved payment links permanently. After
deletion, payment discussions for that context fall back to the
account's bank link.
Args:
payment_link_id: The link's id.
Returns:
{"success": True, "deleted_id": ...} or an error when not found.
Inputs: payment_link_id (required).
Delete a recurring transaction template.
Already-spawned children are NOT touched (they're real
transactions in the user's history). Only the template stops
producing future instances.
Args:
template_id: The template Transaction.id
Inputs: template_id (required).
Delete one of the user's scheduled reminders permanently.
Args:
reminder_id: The reminder's id.
Returns:
{"success": True, "deleted_id": ...} or an error when not found.
Inputs: reminder_id (required).
Delete (archive) a what-if scenario.
Soft-delete — the scenario is hidden but retained.
Args:
scenario_id: The scenario to delete.
Returns:
{"success": True, "deleted_scenario_id": id} or {"error": "..."}.
Inputs: scenario_id (required).
Delete a tag. The tag is removed from every transaction it was attached to, but the transactions themselves are untouched.
Inputs: tag_id (required).
Delete a transaction and reverse its balance effect on the account.
Args:
transaction_id: The ID of the transaction to delete
Returns:
Confirmation with updated account balance
Inputs: transaction_id (required).
Snooze the spending-recommendation nudge for a budget for 30 days.
Mirrors the web "dismiss recommendation" action — sets the budget's
``recommendation_dismissed_until`` to 30 days from today so the
over/under-spending suggestion stops surfacing until then. Does not
change the budget amount or any spending data.
Args:
budget_id: The budget to snooze the recommendation for (the
caller's own, active).
Returns:
``{"success": True, "budget_id": ..., "dismissed_until":
"YYYY-MM-DD"}`` or ``{"error": "..."}`` if not found.
Inputs: budget_id (required).
Mark financial milestones as celebrated (user has seen them).
Args:
milestone_ids: List of milestone IDs to dismiss
Returns:
Number of milestones marked as celebrated
Inputs: milestone_ids (required).
Dismiss a stale "past due" payment warning on a debt account.
Applies when the dashboard shows a payment as past due but the user
knows the underlying Plaid data is wrong (e.g. they paid offline
and Plaid hasn't picked it up). Clears next_payment_due_date and
is_overdue; both repopulate on the next Plaid liabilities sync.
Args:
account_id: The Account.id to clear the warning on
Returns:
Status with the cleared fields.
Inputs: account_id (required).
Edit one of the user's own family chat messages. Other members'
messages can't be edited.
Args:
message_id: ID of the message to edit
content: New message text (1-500 chars)
Returns:
Updated message on success, or error dict
Inputs: content (required), message_id (required).
Export all active accounts as CSV text.
Columns: Name, Account Type, Category, Balance, Currency, Institution,
Interest Rate, Credit Limit, Minimum Payment, Term (Months). Mirrors the
web "Export accounts" download and the REST data/export_accounts endpoint
(transactions have a separate CSV export).
Returns:
``{"csv_data": "<csv string incl. header row>", "row_count": N}`` —
active accounts only.
Inputs: no named parameters.
Export the user's full data set — all accounts + all transactions —
as CSV strings plus a base64-encoded ZIP bundle. Premium-only.
Parity with the REST ``/api/v1/data/export_all/`` ZIP download. The
per-resource account and transaction CSV exports are free; this
Premium "export everything" call bundles both in one response.
``zip_base64`` decodes to a real .zip file; the CSV strings are
readable directly.
Returns:
``{"success": True, "accounts_csv": "...", "transactions_csv":
"...", "zip_base64": "...", "filename": "zoninga_export_YYYY-MM-DD.zip",
"account_count": N, "transaction_count": M}``, or
``{"error": "..."}`` if not Premium.
Inputs: no named parameters.
Export transactions as CSV data.
Args:
account_id: Filter to a specific account (optional)
start_date: Start date YYYY-MM-DD (optional)
end_date: End date YYYY-MM-DD (optional)
Returns:
CSV data as a string with column headers
Inputs: end_date, account_id, start_date.
Project cash flow for the next N months based on recent patterns.
Uses 3-month averages of income and expenses as a baseline AND
biases each future month by recurring templates the user has
scheduled but that haven't fired yet (Phase 115). Templates that
have already fired at least once are folded into the historical
baseline, so they're not counted twice.
Each projection row carries ``scheduled_income_added`` and
``scheduled_expenses_added``, which separate the part of the
projection that comes from "what's already happening" from
"what's scheduled to start." The top-level
``scheduled_templates_count`` is the number of un-fired templates
contributing to the bias — when 0, the projection is purely
historical.
Args:
months_ahead: Number of months to project (default 3, max 12).
Values <= 0 return a validation error; values > 12 are clamped
to 12 and the response sets clamped_months_ahead=true while
requested_months_ahead echoes the original input.
account_id: Optional - project for a specific account only
Returns:
Current balance, average monthly income/expenses/net,
monthly projections (each with the scheduled-bias breakout),
``scheduled_templates_count``, and a human-readable note.
Inputs: account_id, months_ahead.
Get detailed information about a specific account.
Args:
account_id: The ID of the account to retrieve
Returns:
Account details including recent transactions.
Debt accounts include Plaid enrichment: is_overdue, loan_status,
has_pmi, has_prepayment_penalty, last_statement_balance,
next_payment_due_date, last_payment_amount/date,
ytd_interest/principal_paid, and credit card APR breakdown.
Inputs: account_id (required).
Health check across all accounts.
Identifies accounts that need attention: high credit utilization,
no recent activity, approaching limits.
Returns:
List of accounts with status (healthy/warning/critical),
balance, credit utilization, interest rate, days since
last transaction.
Inputs: no named parameters.
Get transaction history for a specific account with running balance.
Shows transactions in reverse chronological order with a running
balance column, useful for seeing how the balance changed over time.
By default, only transactions dated **today or earlier** are returned
— this keeps the running-balance trail anchored to the live
``current_balance``. Pass ``include_scheduled=True`` to also see
future-dated rows (e.g. recurring transactions the cron will spawn);
when scheduled rows are included, the running-balance walk anchors at
the projected balance (``current_balance`` plus the sum of unapplied
future impacts) so the math still reconciles, and each future row
carries an ``is_scheduled: True`` flag.
Args:
account_id: Account to show history for
limit: Maximum transactions to return (default 50, max 200)
include_scheduled: When False (default), filter out future-dated
rows. When True, include them and walk from the projected
balance.
Returns:
Account info and transaction history with running balances.
Response includes ``include_scheduled`` so callers know which
view they got and ``projected_balance`` when scheduled rows
are included.
Inputs: account_id (required), limit, include_scheduled.
Get the full transcript of a past AI assistant chat session.
Returns the messages the user exchanged with the in-app Zoninga
Assistant. Useful for summarizing a past conversation or
continuing a thread from a prior session.
Args:
session_id: The chat session's ID.
Returns:
{"session": {...}, "messages": [{role, content, created_at}, ...]}
or {"error": "..."} if not owned by the caller.
Inputs: session_id (required).
Get behavioral guidelines, safety rules, and workflow guidance for the AI agent.
Describes how the assistant operates as the user's personal finance
assistant; intended for the start of a conversation.
Returns:
Structured instructions including role, safety rules, workflows, and limits
Inputs: no named parameters.
Get a balance sheet snapshot showing assets, liabilities, and net worth.
Returns asset and liability breakdowns by account with totals.
Returns:
Balance sheet data with asset/liability detail and net worth.
Inputs: no named parameters.
Get budget performance over time (actual vs budget per month).
Shows utilization percentage, over/under status for each month.
Args:
budget_id: Budget ID (provide this OR category_name)
category_name: Category name of the budget (provide this OR budget_id)
months: Number of months (default 6)
Returns:
Monthly budget amount, actual spent, utilization %, over/under status.
Inputs: months, budget_id, category_name.
Get budget streak data: consecutive months on-budget per category.
Returns:
List of budget streaks with category, consecutive months, and longest streak
Inputs: no named parameters.
Get cash flow analysis (income vs expenses).
Args:
start_date: Start date in YYYY-MM-DD format (defaults to 30 days ago)
end_date: End date in YYYY-MM-DD format (defaults to today)
include_investment_deposits: When False (default), 401(k)/IRA/
brokerage deposits are excluded from income — disposable
cash flow view. When True, they're counted as income —
useful for "total wealth flow" or "where did all my money
go" reporting that includes retirement contributions.
Returns:
Income and expense totals with net cash flow. Includes
``include_investment_deposits`` so the caller knows which view
it just received.
Inputs: end_date, start_date, include_investment_deposits.
Get smart category suggestions for a transaction description.
Uses a 3-strategy engine: user history, Plaid mapping, and keyword rules.
Useful when creating transactions to auto-suggest the right category.
Args:
description: Transaction description to match (e.g., "Starbucks", "Amazon")
transaction_type: Optional filter — "income" or "expense"
Returns:
Ranked list of suggested categories
Inputs: description (required), transaction_type.
Get monthly spending trend for a specific category.
Shows how spending in a category has changed over time,
including percentage of total spending and month-over-month change.
Args:
category_id: Category ID (provide this OR category_name)
category_name: Category name, case-insensitive (provide this OR category_id)
months: Number of months (default 6)
Returns:
Monthly amounts, percent of total spending, and change percentages.
Inputs: months, category_id, category_name.
Get uncelebrated financial milestones (for celebration animations).
Returns:
List of milestone achievements the user hasn't seen yet
Inputs: no named parameters.
Per-connection staleness report: how long since each linked bank
last synced, and exactly which surfaces a stale connection taints.
Answers "is my data up to date?" and shows whether balance, budget
or forecast figures rest on stale bank data. A connection is
flagged stale after 14 days without a successful sync
(threshold_days in the response).
Returns:
``{"items": [...], "stale_count": N, "threshold_days": 14}``.
Each item: institution_name, last_synced_at, days_since_sync,
is_stale, error state, linked accounts (with per-account
days_since_balance_update), affected_budgets (budget names now
missing activity), affects_forecast, and reconnect_url — a
BROWSER deep link. The reconnect runs in the user's browser
(Plaid Link with step-up auth); this tool returns the link.
A closed account can be archived instead, and a manual sync
can refresh a connection that is healthy but merely behind.
Inputs: no named parameters.
Get daily average income, spending, and net for a date range.
Computes the averages server-side, handling partial months and
year-to-date ranges correctly, and provides a monthly breakdown.
Phase 114 — the start date is **clamped to the user's first
transaction date** when that's later than what was requested.
Without this, a user with two months of activity who asks for
the YTD average sees the daily averages roughly halved (divided
by ~120 days when only ~60 had activity). The response carries
``clamped_to_first_activity`` (bool) and ``requested_start_date``.
When ``clamped_to_first_activity`` is True, the averages cover
only the days since the first transaction (e.g. 55 days of data),
not the full requested range.
Args:
start_date: YYYY-MM-DD (defaults to Jan 1 of current year)
end_date: YYYY-MM-DD (defaults to today)
Returns:
Daily averages with monthly breakdown showing income, expenses,
and net for each month in the range, plus the two clamping
metadata fields.
Inputs: end_date, start_date.
Get a debt paydown analysis with payoff projections.
A call with no arguments returns the user's SAVED plan — their chosen
strategy plus their saved extra monthly payment, the same numbers the
Debt Paydown page shows them. Answers questions like "when will I be
debt-free?" / "what's my payoff date?": `debt_free_date` is the
report's computed payoff date, and `strategy` is the plan's strategy.
Passing `strategy` / `extra_monthly` produces a what-if projection
("what if I paid $200 extra?") rather than the saved plan.
Args:
extra_monthly: Extra monthly payment beyond minimums. Omit to use
the user's saved extra payment (their plan).
strategy: Payoff strategy - highest_rate, snowball, variable_snowball,
minimum_payments, highest_balance, highest_payment,
cashflow_index, npv, max_interest_savings. Omit to use
the user's saved plan strategy.
respect_goal_priorities: When True (default), active debt-payoff
goals override strategy ordering for the primary projection.
False shows what the chosen strategy does without goal
interference. The strategies_comparison table shows pure
strategy ordering regardless of this flag.
`this_month` answers "what do I pay this month?" / "which debt
gets my extra?": `this_month.target` is the debt the plan attacks
first (`target_basis`: extra_this_month, or first_rollover when no
extra is set and freed-up payments start rolling to it in
`first_extra_month`). Each row has payment (the amount to send =
minimum_payment + extra), minimum_payment (the account's stated
minimum), and plan_minimum_payment / plan_payment (the projection's
amortized figures, which can differ by a few dollars).
Returns:
Debt payoff timeline (incl. debt_free_date, the computed payoff date),
this_month (per-debt payments + the target debt), interest
savings, strategy comparison, and is_user_saved_plan (True when
the projection is the user's own saved plan).
Inputs: strategy, extra_monthly, respect_goal_priorities.
Get recent family activity feed.
Args:
limit: Maximum entries to return (default: 20, max: 100)
Returns:
List of recent family activities
Inputs: limit.
Get the user's family group info, members, and role.
Returns:
Family group details with member list, or message if not in a group
Inputs: no named parameters.
Calculate a financial health score based on various metrics.
Returns:
Financial health score (0-100) with component breakdowns
Inputs: no named parameters.
Get key financial ratios computed from the user's data.
Returns pre-computed ratios.
Three different "debt-to-income" flavors are returned and they are
not interchangeable; each fits a different use case:
Returns:
- savings_rate_pct: (income - expenses) / income * 100
- expense_ratio_pct: expenses / income * 100
- debt_to_income_ratio: BALANCE-SHEET LEVERAGE RATIO —
total liabilities / annual income, as a multiple (e.g. 2.36).
A normal homeowner sits above 1.0 because mortgage balance
dwarfs annual income; that's expected for this metric and
NOT a sign of financial trouble. Suited to net-worth analysis.
- back_end_dti_pct: MORTGAGE-INDUSTRY BACK-END DTI —
monthly debt service / monthly gross income, as a percent.
28% / 36% are the GSE qualifying-mortgage thresholds. Same
calc the health-score DTI component uses. None when no
debt accounts have ``minimum_payment`` populated.
- front_end_dti_pct: MORTGAGE-INDUSTRY FRONT-END DTI —
housing payment (mortgage P&I + escrow tax + escrow
insurance) / monthly gross income, as a percent. 28% is
the standard threshold. None when the user has no mortgage
accounts. Measures housing affordability, as opposed to
the "all debt" back-end view.
- monthly_debt_service: dollar sum of minimum payments across
active debt accounts (numerator of back_end_dti_pct).
- monthly_housing_payment: dollar sum of mortgage P&I + escrow
across active mortgage accounts (numerator of front_end_dti_pct).
- emergency_fund_months: liquid assets / monthly expenses
- credit_utilization_pct: CC balances / CC limits * 100
- financial_assets / financial_net_worth: FINANCIAL-ONLY view
(excludes hard assets like real estate, vehicles, jewelry).
These differ from the consumer-facing net worth and balance
sheet figures, which *include* hard assets and match the
dashboard.
- Plus: total_liabilities, annual income/expenses
Inputs: no named parameters.
Get a single forum post, optionally with its replies.
Args:
post_id: The post ID.
include_replies: When True (default), include the post's replies.
Returns:
``{"post": {...}, "replies": [{id, post_id, author_id, content,
created_at, updated_at}]}`` (``replies`` omitted when
include_replies is False), or ``{"error": "Forum post not found"}``
(also returned for a staff-only post viewed by a non-staff user).
Inputs: post_id (required), include_replies.
Get the user's gamification summary including badges, streaks, level, and health score.
Returns:
Combined gamification data: badges, streaks, level info, and financial health score
Inputs: no named parameters.
Fetch one Visions & Goals plan in full: SMART clarifications
(Specific / Measurable / Achievable / Relevant / Time-bound answers)
and action plans with their steps.
Args:
vng_goal_id: The plan id (also stored in a linked zoninga
goal's ``vng_goal_id`` field).
Returns:
{"goal": {...clarifications, action_plans...}} or an error dict.
Inputs: vng_goal_id (required).
Project when a financial goal will be reached at the current pace.
Sums contributions over the last 90 days and divides by the number of
months those contributions actually span (clamped to 1-3 months — a
goal funded for only a few weeks is NOT divided across a full 3 months),
then estimates months remaining and a projected completion date.
``pace_window_months`` reports that divisor; a value < 3 means the
projection rests on a short, preliminary window. If the goal has a
target date, also calculates the required monthly contribution to meet
that deadline.
Args:
goal_id: The goal's ID
Returns:
Current progress, avg monthly contribution, pace_window_months,
projected completion date, months remaining, and required monthly
to hit deadline.
Inputs: goal_id (required).
Get an income statement (profit & loss) for a time period.
The window spans exactly ``months`` calendar months back from today.
When that predates the user's first transaction, the start is clamped
to the first-activity date and ``period.clamped_to_first_activity`` is
true (``period.requested_start_date`` echoes the un-clamped start) —
so a "6 months" label backed by only 3 months of real data is
detectable, matching the other analytics tools (rule 35).
Args:
months: Number of months to cover (default: 6). Values <= 0 return
a validation error. Values > 24 are clamped to a 24-month window
but ``period.requested_months`` / ``period.clamped_months`` echo
the original request so the clamp is detectable.
Returns:
Income and expense breakdown by category with totals, plus a
``period`` block with start/end/months + the clamp metadata
(requested_months, clamped_months, requested_start_date,
clamped_to_first_activity).
Inputs: months.
Get the family gamification leaderboard.
Shows rankings by total points, badges earned, and streaks
for all members of your family group.
Returns:
Ranked list of family members with gamification stats.
Inputs: no named parameters.
Get total spending at a specific merchant or matching a description.
Answers questions like "how much have I spent at Amazon/Starbucks?"
Searches transaction descriptions (case-insensitive partial match).
Args:
search_term: Merchant name or description to search for
start_date: YYYY-MM-DD (defaults to 12 months ago)
end_date: YYYY-MM-DD (defaults to today)
Returns:
Total spent, transaction count, average per transaction,
first/last dates, and monthly breakdown.
Inputs: search_term (required), end_date, start_date.
Get the user's agent monitoring plan — what the sentinel watches for
them (bill coverage, low balance, idle surplus, cashflow shortfall,
anomalies) plus the check-in cadence.
While the plan is DRAFT (not yet approved/activated), the sentinel does
nothing — activation is the user's opt-in to hands-off monitoring.
Args:
refresh_snapshot: Also run a fresh survey of the user's finances
(upcoming bills, income cadence, available funds) and include it
as "snapshot" — useful when helping the user set up or review
their plan.
Returns:
{plan: {...}, snapshot?: {...}}
Inputs: refresh_snapshot.
Calculate the user's current net worth.
Includes financial accounts AND hard assets (real estate, vehicles, etc.)
to match the web UI dashboard calculation.
Returns:
Net worth breakdown with assets, liabilities, hard assets, and totals
Inputs: no named parameters.
Get net worth at the end of each month over time.
Reconstructs historical net worth by reversing transactions
from current balances. Shows assets, liabilities, net worth,
and month-over-month change for each period.
Args:
months: Number of months of history (default 12). Values <= 0 and
values > 1200 return a validation error; values > 24 (but <= 1200)
are capped to 24 but ``requested_months`` echoes the original
request, which makes the clamp detectable.
Returns:
Monthly net worth snapshots with change amounts and percentages,
plus ``requested_months`` and ``clamped_to_first_activity``. The
current (in-progress) month row is dated today with is_partial=true.
Inputs: months.
Compare income, expenses, net, and savings rate across periods.
Covers month-over-month, quarter-over-quarter, and year-over-year
comparisons. Each period includes change_from_previous_pct.
Phase 114 — periods that end before the user's first transaction
are dropped, so a brand-new user asking for ``num_periods=6`` may
see fewer rows. Without this filter the leading zero-padding
rows produced misleading change-from-previous percentages (e.g.
-29.7% comparing the user's first real month to a prior $0
month). Response carries ``clamped_to_first_activity`` (bool)
and ``requested_periods``. When clamped, the returned rows are the
full extent of the user's history (e.g. 2 months of data); no
rows exist for the dropped periods.
Args:
period_type: 'month', 'quarter', or 'year'
num_periods: How many periods to include (default 6)
compare_prior_year: Include same period from prior year
Returns:
List of periods with income, expenses, net, savings_rate_pct,
and change percentages, plus the two clamping metadata fields.
Inputs: num_periods, period_type, compare_prior_year.
Get details for a single Plaid item, including the accounts it owns.
Args:
item_id: The PlaidItem.id (not the upstream Plaid item_id)
Returns:
Item metadata + a nested list of linked accounts
(id, name, type, balance, plaid_last_balance_update).
Inputs: item_id (required).
Get the user's XP points, level, and recent point history.
Returns:
Level info, total points, progress to next level, and recent 20 point entries
Inputs: no named parameters.
Monthly savings rate over time.
Shows income, expenses, net, and savings rate percentage for
each month. Answers questions like "is my savings rate improving?"
Phase 114 — months that predate the user's first transaction
are dropped (same logic as the period summary). A brand-new
user asking for a 12-month trend gets only the months they
actually have data for, not 10 leading $0 rows. Response
carries ``clamped_to_first_activity`` and ``requested_months``.
Args:
months: Number of months (default 12)
Returns:
Monthly savings rate data, plus the two clamping metadata
fields.
Inputs: months.
Get one scenario, its hypothetical changes, and the projected impact.
Runs the debt-paydown engine on the user's real debts adjusted by this
scenario's changes and returns the deltas vs their current plan:
payoff-date change, total-interest change, monthly-payment change,
net-worth change, and the best paydown strategy under the scenario.
Args:
scenario_id: The scenario to analyze.
Returns:
{scenario: {...}, items: [...], analysis: {best_strategy,
interest_delta, monthly_payment_delta, net_worth_delta,
baseline_payoff_date, scenario_payoff_date, ...}} or
{"error": "..."} if not found.
Inputs: scenario_id (required).
Get seasonal challenge sets with user's progress.
Returns:
Active, upcoming, and past seasons with per-challenge progress
Inputs: no named parameters.
Get the user's onboarding/setup progress — the agent's setup curriculum.
Reports what the user still needs to be "hands-off ready", computed
from live data. Most useful near the start of a new user's
conversation.
Finish line is "fast to hands-off": at least one account, an income
signal, and an ACTIVE daily-monitoring plan. Budgets and goals are
offered but optional.
Returns:
``is_new_user`` (no accounts yet), ``hands_off_ready`` (all required
steps done), ``next_step`` / ``next_step_label``,
``required_remaining`` (keys), the ordered ``steps`` (each
``{key, label, done, required, detail}``), ``completed_count`` /
``total_count``, and a ``guidance`` string describing the
recommended next setup step. When ``hands_off_ready`` is True,
required setup is complete.
Inputs: no named parameters.
Detect categories with unusually high spending this month.
Compares current month spending to recent monthly averages.
Flags categories where spending exceeds the threshold multiplier.
Args:
months_lookback: Number of months for computing averages (default 3)
threshold: Multiplier threshold (default 2.0 = 2x the average)
Returns:
List of anomalies with category, current amount, average,
ratio, and severity (high/medium).
Inputs: threshold, months_lookback.
Get spending summary grouped by category.
Args:
start_date: Start date in YYYY-MM-DD format (defaults to 30 days ago)
end_date: End date in YYYY-MM-DD format (defaults to today)
Returns:
Spending breakdown by category
Inputs: end_date, start_date.
The user's standing facts in one call (Phase 251): their SAVED debt
plan resolved to THIS month — `saved_plan.this_month.target` is the
debt receiving the extra payment, with `payment`, `minimum_payment`,
`extra`, and `next_payment_due_date` — plus `upcoming_bills` for the
next `days` (declared schedules, Plaid due dates, AND recurring
bills observed in the bank history — `is_inferred: true`),
scheduled income, `checking_available`, and the monitoring plan
status.
Relevant to questions about paying debts, what to pay this month,
bills, upcoming money, or spare cash. For example, a target `payment`
of $252.48 is a $202.48 `minimum_payment` plus a $50 `extra`. A
non-empty `upcoming_bills` means bills are due in the window.
Args:
days: look-ahead window for bills/income (default 14, max 90)
Returns:
{as_of, saved_plan | null, upcoming_bills, upcoming_bills_total,
scheduled_income_total, checking_available, monitoring}
Inputs: days.
Get the user's subscription plan, limits, and trial status.
Returns:
``plan`` (stable plan_type: "free" / "premium_monthly" /
"premium_yearly"), ``is_premium``, ``is_trialing``, optional
``trial_end`` / ``trial_days_remaining``, and ``limits`` — the Free
caps (``max_accounts`` / ``max_transactions_per_month`` /
``max_goals`` / ``max_budgets`` / ``max_plaid_connections``). A
limit of ``0`` means unlimited (Premium plans).
Inputs: no named parameters.
Get one of the user's own support tickets plus its full message thread.
API docs: https://zoninga.com/ai/#support-tickets
Args:
ticket_id: The ticket's ID.
Returns:
``{"ticket": {...}, "messages": [{id, message, is_staff_reply,
sender, created_at}]}`` ordered oldest-first, or
``{"error": "Support ticket not found"}`` for a ticket that
doesn't exist or isn't the caller's (no existence leak).
Inputs: ticket_id (required).
Get count and total of uncategorized transactions.
Identifies transactions that need categorization.
Phase 115 — also returns a per-type breakdown (``by_type``) and
an ``actionable_count``/``actionable_total`` pair (deposits +
withdrawals only, excluding transfers). The income statement
excludes transfers entirely since they move no money in or out,
so an uncategorized TRANSFER counts in ``uncategorized_count``
here but is absent from the income statement's "Uncategorized"
line. ``actionable_count`` answers "what's blocking my income
statement from being clean?"; ``uncategorized_count`` is the
absolute completeness count.
Args:
start_date: YYYY-MM-DD (defaults to Jan 1 of current year)
end_date: YYYY-MM-DD (defaults to today)
Returns:
Count, total amount, percentage of all transactions that are
uncategorized, plus the by_type breakdown and the
actionable (income-statement-relevant) counts.
Inputs: end_date, start_date.
Get the count of unread notifications (for badge display).
Returns:
Unread notification count.
Inputs: no named parameters.
Get the user's display, notification, privacy, and debt-plan preferences.
Returns:
Theme, currency, notification toggles, privacy settings, and the
saved debt-paydown plan (debt_strategy + debt_extra_monthly_payment).
Inputs: no named parameters.
Get the authenticated user's profile information.
Identifies which account the session is operating on. Returns the
user's email, name, and subscription plan.
Returns:
Dictionary with user identity and account details
Inputs: no named parameters.
Get recent weekly financial recaps (Monday summaries).
Args:
limit: Maximum number of recaps to return (default: 5, max: 20)
Returns:
List of weekly recap summaries
Inputs: limit.
Bulk-create accounts from CSV text.
Parity with the web account-import flow, adapted for a chat agent: pass
the CSV as text (not a file). Columns are auto-detected (name + type are
required; balance, institution, interest_rate, credit_limit,
minimum_payment, term_months optional). Rows that can't be parsed are
skipped and reported; valid rows still import. Created atomically.
Account type accepts friendly strings (checking, savings, cash, credit
card, loan, mortgage, student loan, investment, other asset, other
debt). Respects the Free-plan account cap — if existing + new accounts
would exceed it, the whole import is rejected before any insert.
Args:
csv_text: CSV content as a string (header row + account rows). Max
1000 rows.
skip_duplicates: When True (default), skip rows whose name matches
an existing active account. When False, a duplicate name still
imports (creating a second account with that name).
Returns:
``{"success": True, "imported_count": N, "skipped_duplicates": K,
"error_count": M, "errors": [...up to 20...], "account_names":
[...]}`` on success, or ``{"error": "..."}`` (empty/invalid CSV, no
valid rows, all duplicates, or account-limit exceeded).
Inputs: csv_text (required), skip_duplicates.
Bulk-import transactions into one account from CSV text.
Parity with the REST ``/api/v1/data/import_transactions/`` upload,
adapted for a chat agent: pass the CSV as text (not a file). All rows
are created atomically under a row lock and the account balance is
updated in one pass.
CSV format: a header row then ``date,description,amount,type``.
- date: YYYY-MM-DD (also accepts MM/DD/YYYY or MM/DD/YY)
- amount: positive number ($ and commas are stripped)
- type: deposit/income/credit → deposit; withdrawal/expense/debit →
withdrawal; blank → ``default_type``. (No transfers — import each
side as a deposit/withdrawal.)
Rows that can't be parsed are skipped and reported in ``errors``;
valid rows still import.
On debt accounts the deposit/withdrawal meaning is inverted (a
``deposit`` is a charge that increases the debt,
a ``withdrawal`` is a payment that decreases it) — the balance math is
identical either way. Future-dated rows are created but not applied to
the balance until their date arrives (matching single-transaction
creation).
Args:
account_id: Target account (the caller's own, active).
csv_text: The CSV content as a string (header + rows). Max 1000
rows per call — split larger files.
default_type: Type for rows with a blank ``type`` column
("deposit" or "withdrawal", default "withdrawal").
Returns:
``{"success": True, "imported_count": N, "error_count": M,
"errors": [...up to 20...], "new_account_balance": ...,
"account_name": ...}`` on success, or ``{"error": "..."}`` (account
not found, empty/invalid CSV, monthly-limit exceeded, or no valid
rows).
Inputs: csv_text (required), account_id (required), default_type.
Join a challenge for the current period.
Args:
challenge_slug: The slug identifier of the challenge to join
Returns:
Confirmation with challenge details and period dates
Inputs: challenge_slug (required).
Leave an active challenge for the current period.
Removes the user from the challenge so it can be re-joined later (a
re-join re-counts the period's activity). Completed challenges are not
affected.
Args:
challenge_slug: The slug identifier of the challenge to leave
Returns:
Confirmation, or an error if the user wasn't in that challenge.
Inputs: challenge_slug (required).
Voluntarily leave your current family group. The group owner can't
leave; the error points them to deleting the group on the Family page.
Returns:
Confirmation on success, or error dict
Inputs: no named parameters.
Link (or unlink) a zoninga goal to a Visions & Goals plan.
Args:
goal_id: The zoninga goal id (owned by the user).
vng_goal_id: The V&G plan id to link — verified against the
user's linked V&G account. Pass null/omit to UNLINK.
Returns:
{"success": True, "goal_id": ..., "vng_goal_id": ...} or an
error dict.
Inputs: goal_id (required), vng_goal_id.
List all financial accounts for the user.
Args:
account_type: Filter by type (checking, savings, credit_card, loan, investment, other)
include_hidden: Include hidden accounts (default: False)
limit: Maximum number of accounts to return (default: 50, max: 200).
offset: Number of accounts to skip for pagination (default: 0).
Returns:
Dictionary with a paginated accounts list (``total_count`` /
``has_more`` / ``offset`` / ``limit``) and a ``summary`` that
reflects ALL active accounts — household-wide, regardless of the
page AND of ``account_type`` (its net_worth is the real net
worth in every case). With ``account_type`` set, ``filtered_subtotal`` adds the
count and total balance of the matching active accounts. Debt
accounts include Plaid enrichment: is_overdue, balance_status,
loan_status, next_payment_due_date.
Inputs: limit, offset, account_type, include_hidden.
List the user's past AI assistant chat sessions.
Useful for answering "what did we discuss last time?" or helping
the user find a specific past conversation. Returns the most
recently updated sessions first. Transcripts are not included.
Args:
limit: Maximum number of sessions to return (1-50, default 10).
Returns:
{"sessions": [{id, title, is_active, message_count, ...}, ...],
"count": N}
Inputs: limit.
List all badges with their earned/unearned status for the user.
Args:
category: Filter by badge category (milestone, goal, budget,
financial_health, family, streak, seasonal)
Returns:
All badges grouped by category with earned status and dates
Inputs: category.
List all budgets for the user.
Args:
month: Filter by month in YYYY-MM format (defaults to current month)
limit: Maximum number of budgets to return (default: 50, max: 200).
offset: Number of budgets to skip for pagination (default: 0).
Returns:
List of budgets with spending progress, plus ``total_count`` /
``has_more`` / ``offset`` / ``limit`` pagination metadata. The
``summary`` totals cover ALL budgets for the month, not just the
returned page.
Inputs: limit, month, offset.
List all available categories.
Args:
category_type: Filter by type (income or expense)
Returns:
List of categories grouped by type
Inputs: category_type.
List challenges: active (with progress), available to join, and completed.
Returns:
Active challenges with progress, available challenges, and completed count
Inputs: no named parameters.
List the user's debt payment rules.
Args:
is_active: Filter by active/inactive (default: show all)
Returns:
{rules: [...], count: N}
Inputs: is_active.
List matched debt payments (pending / confirmed / rejected).
Args:
status: Filter by status (pending, confirmed, rejected). Default: all.
limit: Max number of records to return (default 20, max 200)
Returns:
{payments: [...], count: N}
Inputs: limit, status.
Get recent family chat messages.
Args:
after_id: Only return messages after this ID (for polling)
limit: Maximum messages to return (default: 50, max: 100)
Returns:
List of chat messages
Inputs: limit, after_id.
List pending family invitations sent to you or by you.
Returns:
Invitations you've received and invitations you've sent.
Inputs: no named parameters.
List all members in your family group with roles and join dates.
Returns:
List of family members with role and status info.
Inputs: no named parameters.
List active forum categories.
Returns:
``{"categories": [{slug, name, description, icon, is_staff_only}],
"count": N}``. A ``slug`` identifies the category when listing
or creating posts.
Inputs: no named parameters.
List recent forum posts, newest first (pinned posts first).
Args:
category_slug: Filter by category slug (optional). An unknown slug
raises a validation error.
limit: Max posts to return (default 20, max 100)
offset: Number of posts to skip for pagination (default: 0)
Returns:
``{"posts": [{id, category_slug, author_id, title, content,
is_pinned, is_locked, reply_count, created_at, updated_at}],
"total_count": N, "has_more": bool, "offset": N, "limit": N}``.
Staff-only categories are excluded for non-staff.
Inputs: limit, offset, category_slug.
List the user's goal PLANS on Visions & Goals (the sister site for
clarifying and planning goals — SMART criteria, action steps).
These are qualitative plans, separate from the money-tracking
zoninga goals. A plan and a goal can be linked via ``vng_goal_id``.
Returns:
{"goals": [{id, title, timeframe, priority, target_date,
is_achieved, smart_score, action_plan {count,
completion_percentage}, edit_url, ...}], "count": N} — or an
error with a hint when the accounts aren't linked yet.
Inputs: no named parameters.
List the user's financial goals.
Default scope: active + completed goals (cancelled goals are
hidden by default to avoid cluttering responses with abandoned
targets, which accumulate over time). Pass
``include_cancelled=True`` or an explicit ``status="cancelled"``
to see them.
Args:
status: Filter by a single status — "active", "completed",
or "cancelled". When provided, ``include_cancelled``
is ignored.
include_cancelled: If True (and ``status`` is None), include
cancelled goals in the default active+completed listing.
limit: Maximum number of goals to return (default: 50, max: 200).
offset: Number of goals to skip for pagination (default: 0).
Returns:
List of goals with progress info, plus ``total_count`` /
``has_more`` / ``offset`` / ``limit`` pagination metadata.
Inputs: limit, offset, status, include_cancelled.
List all hard assets (real estate, vehicles, valuables) for net worth tracking.
Returns:
List of hard assets with categories, values, and depreciation info.
Inputs: no named parameters.
List all milestones for a goal, ordered by target amount.
Args:
goal_id: The goal whose milestones to list
Returns:
Ordered list of milestones with target amount and reached status
Inputs: goal_id (required).
List notifications for the user.
Args:
unread_only: Only show unread notifications (default: True)
limit: Maximum number of notifications to return (default: 20, max: 100)
offset: Number of notifications to skip for pagination (default: 0)
Returns:
List of notifications plus ``unread_count`` (the full unread
total, regardless of filter) and ``total_count`` / ``has_more`` / ``offset`` / ``limit``
pagination metadata for the current filter.
Inputs: limit, offset, unread_only.
List the user's recent Stripe payment history.
Args:
limit: Maximum rows (default: 10, max: 100)
Returns:
``{"payments": [...]}`` with id, status, amount, currency,
created_at, plan_name, description, and invoice_pdf_url.
Inputs: limit.
List the user's saved payment links — external URLs the user provided
for specific payment contexts (e.g. "child support" → the state
child-support portal).
For a matching payment context, a saved payment link takes precedence
over the source account's bank login link (institution_url).
``url_host`` is the hostname, suitable as visible link text so the
destination is shown.
Returns:
{"payment_links": [{id, label, url, url_host, updated_at}, ...],
"count": N}
Inputs: no named parameters.
List all Plaid bank connections (items) for the user.
Each item represents one institution (one bank login). A single
item can hold multiple Account rows (checking + savings + credit
card from the same bank).
Args:
include_inactive: Include unlinked / soft-deleted items (default: False)
Returns:
``{"items": [...], "total_count": N}`` where each item carries
id, institution_name, products (consented), last_synced_at,
is_active, error_code/message, consent_expiration_time, and
the count of currently-linked accounts.
Inputs: include_inactive.
List the user's recurring transaction templates.
Templates are the parent rows that the daily cron spawns child
transactions from. Spawned children appear in the regular
transaction listing, not here.
Returns:
``{"templates": [...], "total_count": N}`` — each template
includes id, description, amount, frequency, start/end date,
and the running ``instances_generated`` count.
Inputs: no named parameters.
List the user's scheduled reminders — texts they asked the agent to
resurface on a schedule (delivered in the morning brief, and in the
brief email when they've opted in).
Args:
include_inactive: Also include delivered one-time and deactivated
reminders (default False).
Returns:
{"reminders": [...], "delivery_note"?: str} — delivery_note appears
when the brief cadence means reminders won't actually be delivered.
Inputs: include_inactive.
List the user's saved what-if scenarios (active, not deleted).
Each scenario is a "potential choice" that auto-expires 60 days after
creation. The full projected impact is available per scenario by id.
Returns:
{"scenarios": [{id, name, status, item_count, expires_at, ...}],
"count": N}
Inputs: no named parameters.
List all active subscription plans (Free, Premium monthly/yearly).
Returns:
``{"plans": [...]}`` — each plan includes id, name, plan_type,
price, currency, billing_interval, and the plan's quotas / feature
flags, which together answer "what do I get if I upgrade?" Monthly and yearly Premium are
separate plan rows (distinguished by ``billing_interval``).
Inputs: no named parameters.
List the user's own support tickets, most recently active first.
API docs: https://zoninga.com/ai/#support-tickets
Closed tickets are hidden by default (they're soft-archived once
closed). Pass a ``status`` to change that:
Args:
status: ``None`` (default) hides closed tickets. ``"all"`` shows
every ticket including closed. A specific status —
``open``, ``in_progress``, ``resolved``, ``closed`` — filters
to exactly that. Any other value raises a validation error.
limit: Max tickets to return (1-100, default 20).
Returns:
``{"tickets": [{id, subject, category, category_display, status,
status_display, priority, priority_display, message_count,
created_at, updated_at}], "count": N}``.
Inputs: limit, status.
List all tags the user has defined.
Returns:
``{"tags": [...], "total_count": N}`` — each tag has id,
name, color (hex), and how many transactions currently carry it.
Inputs: no named parameters.
List all available color themes with the user's active theme.
Returns:
List of themes with active status
Inputs: no named parameters.
List transactions with optional filters.
Args:
account_id: Filter by account ID
category_name: Filter by category name (case-insensitive)
transaction_type: Filter by type (deposit or withdrawal)
start_date: Start date in YYYY-MM-DD format
end_date: End date in YYYY-MM-DD format
search: Search in description
tag_name: Filter by tag name (case-insensitive)
limit: Maximum number of transactions to return (default: 50, max: 200)
offset: Number of transactions to skip for pagination (default: 0)
count_only: If true, return only the total count and totals without transaction details (faster for counting)
Returns:
List of transactions plus ``total_count`` (untruncated) and pagination info.
Each row carries ``economic_class`` (income / expense / transfer /
balance_sheet), the income-vs-spending classification. Raw
``transaction_type`` differs from it on debt accounts: a credit-card
CHARGE is stored as ``deposit`` and a card PAYMENT as ``withdrawal``.
``totals`` (deposits/withdrawals/net) is aggregated over the ENTIRE matching
window in BOTH normal and count_only modes — NOT just the returned page — so a
paginated read reports the full period's income/expenses. The current page's
subtotal is the sum of the per-row ``amount`` values.
SCOPE NOTE: this is a raw transaction listing and INCLUDES rows on
archived (inactive) accounts — like the CSV export, it's the user's
complete history. The cash-flow, spending, uncategorized-summary and
other analytics reports EXCLUDE archived-account transactions, so their
totals differ from a raw list over the same window when the user has
archived accounts. Filtering by an active ``account_id`` matches the
analytics scope.
Inputs: limit, offset, search, end_date, +6 more.
Mark notifications as read.
Args:
notification_id: ID of a single notification to mark as read
mark_all: Set to True to mark all notifications as read
Returns:
Confirmation with count of updated notifications
Inputs: mark_all, notification_id.
Create a Stripe Billing Portal session and return the URL.
The portal lets the user update their payment method, view
invoices, and download receipts. Returns ``{"portal_url": "..."}``
or ``{"error": ...}``.
Inputs: no named parameters.
Manually correct a Plaid-linked account's balance.
When Plaid reports a stale or incorrect balance (mismatched institution
feed, delayed clearing, etc.), the user can override it. The override
is preserved on subsequent Plaid syncs until Plaid reports a genuinely
different (refreshed) balance — at which point the override clears
automatically.
Only works on Plaid-linked accounts. A manual account's balance is
edited directly on the account itself.
Args:
account_id: The Plaid-linked account to override
new_balance: The correct balance (supports negative for overdraft
or credit card balances > credit_limit)
Returns:
Updated account snapshot with new balance and `balance_status`
Inputs: account_id (required), new_balance (required).
Parse a base64-encoded PDF bank/credit-card/loan statement and return
the extracted fields WITHOUT saving anything. Premium-only.
This is step 1 of a two-step flow: the extracted values are reviewed
with the user, and a separate apply step writes the confirmed values
to a specific account. Nothing is persisted by this tool.
Args:
pdf_base64: The PDF file encoded as a base64 string (<= 5 MB
decoded). Image-only/scanned PDFs aren't supported.
Returns:
``{"success": True, "fields": {...}, "fields_found": N,
"account_type_hint": "credit_card"|"mortgage"|...|None}`` where
each entry in ``fields`` is
``{"value": "1234.56", "confidence": 0.9, "source_text": "...",
"source": "regex"}`` (the same shape the REST parse returns). The
``value`` strings are the inputs the apply step accepts.
On failure: ``{"error": "..."}`` (not Premium, bad base64, not a
PDF, too large, or unparseable).
Inputs: pdf_base64 (required).
Undo a pending cancellation (only works while the subscription is still in its current paid period).
Inputs: no named parameters.
Apply a category to ALL of the user's transactions that share an exact
description and type (case-insensitive description match).
Mirrors the web "recategorize similar" prompt: after fixing one
transaction's category, sweep every other transaction with the same
description + type into that category. Useful for cleaning up a
recurring merchant in one shot.
Args:
description: The exact transaction description to match
(case-insensitive; whole-string, not a substring).
transaction_type: 'deposit', 'withdrawal', or 'transfer' — only
transactions of this type are matched.
category_name: Category to assign (case-insensitive; user-owned or
system).
exclude_transaction_id: Optional transaction id to skip (e.g. the
one the user already categorized).
Returns:
``{"success": True, "updated": N, "category": ..., "category_id":
...}`` (``updated`` may be 0 if nothing else matched), or
``{"error": "..."}`` on validation failure.
Inputs: description (required), category_name (required), transaction_type (required), exclude_transaction_id.
Reject a pending debt payment match. The source transaction is left
unchanged; no debt-account transaction is created.
Args:
debt_payment_id: ID of the pending DebtPayment record to reject
Returns:
Updated debt payment details
Inputs: debt_payment_id (required).
Remove a member from your family group. Requires owner or admin role.
The group owner can't be removed.
Removes all shares involving the target member.
Args:
member_id: FamilyMember ID (not user ID) — as shown in the group's members list
Returns:
Confirmation on success, or error dict
Inputs: member_id (required).
Rename one of the user's AI assistant chat sessions.
Args:
session_id: The chat session's ID.
title: New title (1-100 chars after strip).
Returns:
{"success": True, "session": {...}} or {"error": "..."}.
Inputs: title (required), session_id (required).
Set the dashboard display order of the user's accounts.
Args:
account_ids: Account IDs in the desired top-to-bottom order. Every id
is required to be one of the user's active accounts. Any active account you
omit keeps its current order value, so pass the full list for a
deterministic ordering.
Returns:
``{"success": True, "reordered": N}``, or ``{"error": ...}`` if any id
isn't one of the user's active accounts.
Inputs: account_ids (required).
Reply to one of the user's own support tickets.
If the ticket was resolved or closed, replying reopens it (the
service layer handles this), so the user can resume the conversation.
Writes to Zoninga's own support desk (no third-party service).
API docs: https://zoninga.com/ai/#support-tickets
Args:
ticket_id: The ID of the ticket to reply to.
body: The reply text (1-5000 chars).
Returns:
``{"success": True, "reply": {...}, "ticket": {"id", "status"}}``
(``ticket.status`` reflects any reopen), or ``{"error": "..."}``
if the ticket isn't found / isn't the caller's, or the body is
invalid.
Inputs: body (required), ticket_id (required).
Reset the authenticated user's onboarding state.
Covers requests like "can we restart the tour" or "reset my
setup checklist". Passing just one of the flags is fine — omitting
both is a no-op (returns success with nothing changed).
Args:
reset_tour: Set to True to replay the spotlight tour on next
login (clears ``UserPreferences.has_seen_tour``).
reset_checklist: Set to True to clear every ``checklist_*``
completion flag AND re-show the checklist widget.
Returns:
{"success": True, "reset_tour": bool, "reset_checklist": bool}
reflecting which pieces were reset.
Inputs: reset_tour, reset_checklist.
Revoke (cancel) a pending invitation YOU sent, before it's accepted.
The id is the one shown in the user's "sent" invitations — e.g.
to withdraw an invitation sent to the wrong address. Only group
owners/admins can revoke. (2026-07-19: closes the QA-sweep gap where
a sent invitation was unremovable from the agent surface.)
Args:
invitation_id: ID of the sent invitation to revoke.
Returns:
{"success": True, "email": ...} or an error when not found /
not pending / not yours to revoke.
Inputs: invitation_id (required).
Save (or update) the external payment URL for one payment context.
Use when the user gives or corrects a link — e.g. "for child support
use https://childsupport.state.mn.us". Saving a label that already
exists (case-insensitive) UPDATES that link's URL.
Intended for URLs the user explicitly provided or confirmed, not
found, guessed, or constructed ones. https only; a bare domain like "chase.com" is normalized to
https://; javascript:/http:/IP-literal/credential-bearing URLs are
rejected.
Args:
label: The payment context name (max 100 chars), e.g. "child support".
url: The user-provided payment page URL (https).
Returns:
{"success": True, "created": bool, "payment_link": {...}} —
created is False when an existing label's URL was updated.
Inputs: url (required), label (required).
Send a message in the family group chat.
Args:
content: Message text (max 500 characters)
Returns:
The sent message details
Inputs: content (required).
Send a family group invitation to an email address. Requires the group owner or admin role.
Args:
email: Email address to invite
message: Optional personal message
Returns:
Confirmation of invitation sent
Inputs: email (required), message.
Create a Stripe Checkout session and return the URL for the user
to open in a browser to complete payment.
Args:
plan_id: SubscriptionPlan.id to subscribe to (a paid plan only)
Returns:
``{"checkout_url": "...", "plan_name": "..."}`` or ``{"error": ...}``.
The URL opens Stripe Checkout in the user's browser; checkout
cannot be driven programmatically. A user with a live paid
subscription gets an error pointing at the billing portal; a
user whose Premium is comped (or free in beta) still gets the URL
plus ``already_premium_note``, which explains they already have
Premium access.
Inputs: plan_id (required).
Suggest a description pattern for a new debt-payment rule.
Scans recent withdrawals on the source (asset) account for ones whose
description contains the debt account's institution name — the same
helper the web "suggest pattern" button uses. Read-only (suggests, does
not create a rule). The returned ``pattern`` is in the format
debt-payment rules accept.
Args:
source_account_id: The asset account the payment comes from.
debt_account_id: The debt account being paid.
Returns:
``{"pattern": str|None, "sample_transactions": [{id, description,
amount, date}]}`` — ``pattern`` is None when the debt account has no
institution set or no matching withdrawals were found. Returns
``{"error": "..."}`` if either account isn't the caller's.
Inputs: debt_account_id (required), source_account_id (required).
Revoke the current session and force re-authorization.
Relevant when the session is authenticated as the wrong user. After
this runs, the connector prompts for re-authorization, and the
'Use a different account' link on the consent page signs in as a
different user.
Returns:
Dictionary with status and instructions
Inputs: no named parameters.
Trigger an on-demand transaction sync for one Plaid item.
Same code path as the daily cron — pulls new transactions since
the last cursor and applies them to the matched accounts.
Args:
item_id: The PlaidItem.id to sync
Returns:
Sync result counters (added/modified/removed transaction counts).
Inputs: item_id (required).
Restore a soft-deleted transaction created manually. Only works
for transactions deleted (via MCP or the web UI) within the last
7 days. Plaid-managed transactions cannot be
undone (they are hard-deleted on their original delete).
Args:
transaction_id: The ID of the soft-deleted transaction to restore
Returns:
The restored transaction details, or an error dict
Inputs: transaction_id (required).
Unlink a Plaid item (soft-deactivate) and revoke the upstream
access token at Plaid.
Linked accounts are NOT deleted — they're detached from Plaid and
become manual accounts (the user keeps their transaction history).
Args:
item_id: The PlaidItem.id to unlink
Returns:
Status with the institution name and detached-account count.
Inputs: item_id (required).
Update an existing financial account.
Args:
account_id: The account ID to update
name: New account name (optional)
account_type: New account type (optional). One of: checking, savings,
cash, credit_card, loan, mortgage, student_loan, heloc, arm,
investment, other_asset, other_debt
balance: New balance amount (optional, use with caution)
institution: New institution name (optional)
currency: New currency code. App is locked to USD pre-launch — any
other value is rejected. (See docs/CURRENCY_RESTORE_TODO.md.)
is_active: Set account active/inactive (optional). True on an archived
account restores it, subject to the plan's account limit and to no
other active account having the same name.
interest_rate: New interest rate for debt accounts (optional)
credit_limit: New credit limit for credit cards (optional)
minimum_payment: New minimum payment for debt accounts (optional)
term_months: Original loan term in months (optional)
loan_start_date: Loan origination date YYYY-MM-DD (optional)
loan_end_date: Loan payoff target date YYYY-MM-DD (optional)
original_balance: Original loan amount when first taken out (optional)
monthly_escrow_tax: Monthly property tax escrow, mortgage only (optional)
monthly_escrow_insurance: Monthly insurance escrow, mortgage only (optional)
draw_period_months: HELOC draw-phase duration in months (optional)
draw_amount_per_month: HELOC monthly draw amount (optional)
rate_2: 2nd-term rate as percentage, HELOC/ARM (optional)
term_2_months: 2nd-term duration in months, HELOC/ARM (optional)
arm_initial_period_months: ARM fixed-rate period in months (optional)
include_in_debt_paydown: Include this debt in the payoff calculator
and dashboard payoff card (optional). Set False for a debt you
pay in full each month so it doesn't distort the plan; does NOT
affect net worth, total debt, or the balance sheet.
low_balance_alert_threshold: Per-account low-balance alert
threshold in dollars — "alert me when this account drops below
$X" (checking/savings/cash). Overrides the monitoring plan's
global threshold for this account only.
clear_low_balance_threshold: Set True to remove a per-account
threshold and fall back to the plan's global default.
mute_low_balance_alerts: True = no low-balance alerts on this
account (daily brief + notifications) — "stop reminding me,
I know this account is low". False = re-enable alerts.
institution_login_url: Where the user logs in at this institution
(https only, e.g. "https://chase.com"; bare domains are
normalized to https). An empty string removes the link. Intended
for a URL the user provided, not a guessed or invented one.
Returns:
Updated account details
Inputs: account_id (required), name, rate_2, balance, +22 more.
Update an existing budget.
Args:
budget_id: The ID of the budget to update
amount: New budget amount (optional)
period: New period - "monthly" or "yearly" (optional)
rollover: Enable/disable rollover (optional, monthly budgets only)
name: New display name (optional, Phase 92). Pass an empty string to
clear the custom name and fall back to the category name.
Returns:
Updated budget details
Inputs: budget_id (required), name, amount, period, +1 more.
Update a user-created category. System categories cannot be modified.
Args:
category_id: The category ID to update
name: New category name (max 50 chars)
Returns:
Updated category details
Inputs: category_id (required), name.
Update the pattern or account pairing on an existing debt payment rule.
Args:
rule_id: ID of the rule to update
description_pattern: New substring to match (optional, <=200 chars)
source_account_id: New asset account (optional)
debt_account_id: New debt account (optional)
Returns:
Updated rule details
Inputs: rule_id (required), debt_account_id, source_account_id, description_pattern.
Update an existing forum post (author only).
Args:
post_id: The post to update.
title: New title (3-200 chars).
content: New raw markdown content (10-10000 chars).
Returns:
``{"success": True, "post": {...}}`` on success, or
``{"error": "..."}`` (not found, not the author, or validation).
Inputs: title (required), content (required), post_id (required).
Update an existing forum reply (author only).
Args:
reply_id: The reply to update.
content: New raw markdown content (5-10000 chars).
Returns:
``{"success": True, "reply": {...}}`` on success, or
``{"error": "..."}`` (not found, not the author, or validation).
Inputs: content (required), reply_id (required).
Update an existing financial goal.
Args:
goal_id: The ID of the goal to update
name: New goal name (optional)
target_amount: New target amount (optional, may auto-complete if <= current amount)
target_date: New target date in YYYY-MM-DD format (optional)
status: New status - active, completed, paused, cancelled (optional)
color: New hex color code (optional)
notes: New notes (optional)
priority: New priority level (optional)
Returns:
Updated goal details
Inputs: goal_id (required), name, color, notes, +4 more.
Update a hard asset's details.
Args:
asset_id: ID of the hard asset to update
name: New name (optional)
current_value: Updated current value (optional)
description: Updated description (optional)
location: Updated location (optional)
Returns:
Updated hard asset details.
Inputs: asset_id (required), name, location, description, +1 more.
Update a milestone's name, target amount, or celebration message.
Args:
milestone_id: The milestone ID to update
name: New name (optional)
target_amount: New target (> 0 and <= parent goal's target)
celebration_message: New celebration message (optional)
Returns:
Updated milestone details
Inputs: milestone_id (required), name, target_amount, celebration_message.
Update (and optionally activate) the user's monitoring plan.
Only the fields passed are changed. Part of onboarding: activate=True
turns hands-off monitoring on and is intended to follow the user's
explicit confirmation in the conversation.
The plan drives notifications and Tier-2 proposals only — it moves
no money.
Args:
check_in_frequency: daily / weekly / monthly / off.
watch_*: toggle individual watchers.
low_balance_threshold: alert when an account drops below this ($).
surplus_buffer: keep at least this much in checking ($).
surplus_minimum_sweep: minimum sweep size proposed ($); smaller
sweeps aren't proposed.
watch_cashflow_shortfall / watch_anomalies: forecast + anomaly watchers.
watch_new_recurring / watch_duplicates / watch_quiet_account:
elder-watch trio — new recurring charge inference, possible
double-posted charges, and spending on a normally-quiet
account (all informational; nothing moves money).
watch_goals: goal alerts. Flags a goal with a target date that is
behind pace, due within 30 days, or past its date unfinished.
activate: set True (with the user's explicit OK) to approve the plan
and start the sentinel.
Returns:
{"success": True, "plan": {...}} or {"error": ...}.
Inputs: activate, watch_goals, watch_surplus, surplus_buffer, +10 more.
Update a recurring transaction template.
Only the fields you pass are updated. Past spawned instances are
left alone — the change applies to future spawns only.
Args:
template_id: The template Transaction.id
amount: New amount (optional)
description: New description (optional)
frequency: New frequency (optional)
end_date: New end date as YYYY-MM-DD, or empty string to clear (optional)
category_id: New category id, or 0/null to clear (optional)
Inputs: template_id (required), amount, end_date, frequency, +2 more.
Update a what-if scenario (only the fields you pass change).
When ``items`` is omitted the existing changes are kept; pass a full
new list to replace them. A committed scenario can't be edited.
Item dict shapes match scenario creation (add_debt / add_asset / remove).
Args:
scenario_id: The scenario to update.
name / description / strategy / extra_monthly: Optional new values.
items: Optional full replacement list of change dicts.
Returns:
{scenario: {...}, analysis: {...}} or {"error": "..."}.
Inputs: scenario_id (required), name, items, strategy, +2 more.
Update a tag's name and/or color. Renaming preserves all transaction associations.
Inputs: tag_id (required), name, color.
Update an existing transaction.
Args:
transaction_id: The ID of the transaction to update
description: New description (optional)
amount: New amount as positive number (optional, will adjust account balance)
category_name: New category name, case-insensitive (optional)
transaction_date: New date in YYYY-MM-DD format (optional)
tag_names: List of tag names to assign (optional, replaces existing tags)
Returns:
Updated transaction details with new account balance
Inputs: transaction_id (required), amount, tag_names, description, +2 more.
Update user preferences. Only provided fields are changed.
Args:
theme: Color theme (light, dark, emerald_banking, frost_glass, carbon)
currency: Currency code. USD only — multi-currency is disabled
pre-launch, so any other value is rejected (matches the web
form + REST serializer, which omit/lock the field).
notify_budget_alerts: Enable budget alert notifications
notify_bill_reminders: Enable bill reminder notifications
notify_large_transactions: Enable large transaction notifications
notify_weekly_summary: Enable weekly summary emails
notify_balance_alerts: Enable Plaid balance-mismatch alert
notifications (off by default — the dashboard badge is the
default signal)
notify_debt_payments: Enable the monthly debt-strategy payment
reminder (requires a saved debt_strategy to fire)
notify_daily_brief_email: Email the agent's morning brief to the
user's inbox (the brief appears in the app thread either
way; this toggles the email copy only)
notify_urgent_alert_email: Email overdraft and bank-fee alerts
the moment the bank reports them (on by default; the alert
appears in the app thread either way)
notify_family_alerts: Receive in-app alerts + the family brief
about accounts a family member shared with the user
(elder-care; on by default, receiver-side opt-out)
notify_family_brief_email: Email the family brief (off by
default; alerts keep appearing in the app either way)
show_profile_picture: Show profile picture in forum
show_real_name: Show real name in forum
show_level: Show level badge in forum
show_badges: Show earned badges in forum
debt_strategy: Save the user's debt-paydown "my plan" strategy — one
of minimum_payments, snowball, variable_snowball, highest_rate,
highest_balance, highest_payment, cashflow_index, npv,
max_interest_savings. Pass "" to clear it. This drives the
dashboard debt-payoff card + the strategy reminder. Free plans are
limited to the lower-tier strategies (Premium-only ones rejected).
debt_extra_monthly_payment: Extra $/month applied on top of minimums
in the paydown plan (0 or positive).
Returns:
Updated preferences (including debt_strategy + debt_extra_monthly_payment)
Inputs: theme, currency, show_level, show_badges, +14 more.
Update the authenticated user's profile fields.
Only the fields you pass are changed. Email is NOT editable here
(changing email requires re-verification on the web). Profile
picture upload is not exposed over MCP — it's web-only.
Args:
first_name: New first name (max 150 chars)
last_name: New last name (max 150 chars)
bio: Short forum bio (max 500 chars)
forum_display_name: Forum display name (max 50 chars). Blank
falls back to a masked email in the forum.
state: Two-letter US state code (e.g. 'CA'). '' clears the field.
Returns:
Updated profile details
Inputs: bio, state, last_name, first_name, +1 more.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Read-only personal finance for AI agents: budgets, receipts, net worth, bills. OAuth 2.1.
Ask your AI about your own accounts, debts, budgets and goals. OAuth sign-in, read-only by default.
Personal finance for AI agents — onboard, import statements, categorize & budget over MCP.
Personal finance tracker: accounts, transactions, budgets, investments and analytics over OAuth.
Add one secure layer between your agents and this server.
