ClearCash

Returns signed net transaction totals broken down by category, subcategory, and merchant for one required granularity: day, week, or month. Amounts use the same sign convention as `list_transactions` across all account types: outflows (spending, bills, loan payments, transfers out) are negative and inflows (income, refunds, transfers in) are positive. Every category is included, including income and transfers, so `period_totals` is net cash flow, not total spending; to total spending, sum only the negative amounts in spending categories and exclude income and transfer categories. `min_amount`/`max_amount` filter on these signed amounts. Breakdown `periods` are period-start dates. `period_totals` is keyed by those same period-start dates. Category-breakdown merchant rows use the same identity contract as merchant breakdown: `id` is the grouping identifier, and enriched merchants also include their stable `entity_id`. The `transaction_ids` array on each merchant row can be passed to `list_transactions` to retrieve the underlying transactions. This tool returns a complete category breakdown for the requested granularity only; if the response would exceed 1 MB the request fails with `response_too_large` — retry with a narrower date range.

get_category_breakdown_aggregates

Returns signed net transaction totals broken down by merchant for one required granularity: day, week, or month. Amounts use the same sign convention as `list_transactions` across all account types: outflows are negative and inflows (income, refunds, transfers in) are positive, so a merchant's total nets purchases against refunds. `period_totals` is net cash flow across all merchants, not total spending. `min_amount`/`max_amount` filter on these signed amounts. `periods` and `period_totals` use period-start dates. For enriched merchants, `id` and `entity_id` are the same stable entity UUID. For unenriched merchants, `entity_id` is null and `id` is a deterministic fallback identifier based on the raw merchant description. The `transaction_ids` array on each merchant row can be passed to `list_transactions` to retrieve the underlying transactions. This tool returns a complete merchant breakdown for the requested granularity only; if the response would exceed 1 MB the request fails with `response_too_large` — retry with a narrower date range.

get_merchant_breakdown_aggregates

Returns a time-series of total net worth values over a date range, stepped by day, month, or year. Use this tool when the user asks about net worth trends, changes over time, or year-over-year comparisons. For a full breakdown at a single point in time (assets, liabilities, account detail) use `get_net_worth_snapshot` instead. All monetary values are raw numerics. `step=day` returns every date in range. `step=month` returns month-end snapshots for complete months plus the requested `end_date` for the current partial month. `step=year` returns year-end snapshots for complete years plus the requested `end_date` for the current partial year.

get_net_worth_history

Returns a point-in-time snapshot of the user's net worth, broken down into assets and liabilities. Assets include financial accounts classified as assets (checking, savings, investments) and property. Liabilities include financial accounts classified as liabilities (credit cards, loans, mortgages). When a `group_id` is provided, the snapshot reflects the shared view for that group, including per-member portions. Personal snapshot account/property rows include both full values and user-share values. `net_worth_contribution` is signed so callers can sum rows without special liability handling. All share percentages use a 0–1 scale. Snapshot account rows include both `account_type` and `account_subtype`. Use this tool when the user asks about their overall financial position, total net worth, or asset/liability breakdown. For net worth trends over time use `get_net_worth_history`. All monetary values are raw numerics. Note: `assets.total` and `liabilities.total` are user-share adjusted — they sum each row's `net_worth_contribution`, so split account balances are weighted by the user's split percentage, not counted at full value.

get_net_worth_snapshot

Returns time-series aggregate metrics for a filtered set of transactions for one required granularity: day, week, or month. Use this tool when the user asks about income, spending, or cash flow over time. For a breakdown by category use `get_category_breakdown_aggregates`. For a breakdown by merchant use `get_merchant_breakdown_aggregates`. Each aggregate row includes both full-amount and user-share metrics: `earning_amount`/`spending_amount`/`cash_flow_amount` use full transaction amounts, while `user_earning_amount`/`user_spending_amount`/`user_cash_flow_amount` use the current user's effective share. Spending values are positive magnitudes; cash flow values are signed. Credit card and loan transactions are normalized so purchases count as spending and refunds count as earning. Earning and spending include transfers between the user's own accounts (e.g. a credit card payment from checking is spending on the checking account and earning on the card), so use the category breakdown to separate transfers from true income and spending. `period_end` is the date of the last transaction in the period, not the calendar end of the period. `cumulative_balance_amount` is the estimated running total of all accessible financial account balances (asset balances minus liability balances); it does not include property values and is not the same as total net worth. When no date range is provided, defaults are applied per granularity: daily rows cover the trailing 30 days, weekly rows cover the trailing 84 days (12 weeks), monthly rows cover the trailing 12 months.

get_transaction_aggregates

Returns context about the authenticated ClearCash user: their display name, subscription tier, and the environment the server is running in. Call this at the start of a session to personalise responses and confirm the environment. No arguments required.

get_user_context

Returns the active ClearCash financial account type catalog, including broad account type, account subtype, classification, display name, and description. Use this tool when the user or caller needs to understand the valid `account_subtype` values accepted by `list_financial_accounts`, `list_loans`, or other account-filtering tools. This is a reference data tool; it does not return user financial balances, institutions, transactions, or sharing metadata.

list_financial_account_types

Returns the financial accounts accessible to the user, including personally held accounts and accounts shared through a ClearCash group. ClearCash groups allow users to share accounts with partners or household members. Shared accounts may be split (user owns a percentage of the balance) or view-only (read access to another user's account). Use this tool to map the user's account landscape before querying transactions or net worth. For a full net worth inventory, combine this with property tools or `get_net_worth_snapshot`, because this tool returns accounts only and not property values. The `access_metadata` field indicates whether the user owns the account (`owner`), has a proportional share (`split`), or has view-only access (`view`). For split accounts, `user_split_percentage` indicates the user's ownership proportion on a 0–1 scale (e.g. 0.5 = 50%). `net_worth_contribution` is analysis-ready: assets match `balance`, liabilities are negated.

list_financial_accounts

Returns the members of a specific ClearCash group. Use this tool to understand who is in a shared finance group, their roles, and their split proportions. `split_percentage` is a fractional share on a 0–1 scale, indicating what proportion of shared account balances and transactions each member is responsible for (e.g. 0.5 = 50%). `is_current_user` identifies which member record belongs to the authenticated user. `user_id` is only returned for the current user's own member record; other members' internal IDs are not exposed. Returns only member fields already visible to the authenticated user in the ClearCash group UI. Requires a `group_id` from `list_groups`.

list_group_members

Returns the ClearCash groups the user belongs to. A ClearCash group is a shared finance arrangement between two or more people (e.g. partners, spouses, household members). Groups are the mechanism through which accounts, transactions, and net worth are shared. Use this tool first when the user asks about shared finances, household spending, or partner accounts — the `group_id` values returned here are required as filters for most other tools when analyzing shared data. Returns only group fields already visible to the authenticated user in the ClearCash group UI. Returns all active groups; no pagination in MVP.

list_groups