get_category_breakdown_aggregates
ChatGPTReturns spending totals broken down by category, subcategory, and merchant for one required granularity: day, week, or month. 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_merchant_breakdown_aggregates
ChatGPTReturns spending totals broken down by merchant for one required granularity: day, week, or month. 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_net_worth_history
ChatGPTReturns 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_snapshot
ChatGPTReturns 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_transaction_aggregates
ChatGPTReturns 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. 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 (both assets and liabilities, with liability balances included at their raw sign); 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_user_context
ChatGPTReturns 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.
list_financial_account_types
ChatGPTReturns 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_accounts
ChatGPTReturns 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_group_members
ChatGPTReturns 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_groups
ChatGPTReturns 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_institutions
ChatGPTReturns the financial institutions (banks, brokerages, credit unions, etc.) connected to the user's ClearCash account. Each institution may hold one or more financial accounts. Use this tool to understand which institutions are connected before querying accounts or transactions. Institutions may be personally owned or shared with a ClearCash group (a household or partner sharing arrangement). The access_metadata field indicates whether the user owns the institution connection (owner) or has shared access to it (split or view). For connection health, use list_financial_accounts, where status is returned at the account/connection level.
list_loans
ChatGPTReturns detailed loan information for the user's loan accounts. Each loan is linked to a financial account — the current balance and display name for the loan are available on the corresponding account from list_financial_accounts using financial_account_id. This tool provides loan-specific detail such as interest rate, term, payment schedule, and payoff timeline that is not available on the account record itself. Loans contribute to the liabilities side of the user's net worth. Use list_financial_accounts with classification = liability to see outstanding balances; use this tool when the user needs interest rates, payment details, or payoff dates.
list_properties
ChatGPTReturns property assets associated with the user's ClearCash account. Accepted property_type values are real_estate, vehicle, boat, collectable, and other. valuation_method currently returns manual. Properties contribute to the assets side of the user's net worth. Date fields such as purchase_date, last_valuation_date, and sold_at are returned as YYYY-MM-DD. Each property includes a value_periods array containing historical valuation periods ordered by valid_from ascending; each period has period_id, value, valid_from, valid_to (null if current), source (manual or zillow), and zillow_value (raw Zillow estimate when source is zillow). By default only active (unsold) properties are returned. Set include_sold to true to include properties the user has sold.
list_transactions
ChatGPTReturns transactions the user is authorized to access within a specified date range. Transactions may come from personally held accounts or accounts shared through a ClearCash group. reporting_amount is always the full signed transaction amount in the reporting currency. user_split_percentage and user_reporting_amount represent the current user's effective share on a 0–1 scale and in the reporting currency, respectively, regardless of ownership. Expenses/debits are negative; income/credits are positive. transaction_date is returned as YYYY-MM-DD. A date range is required; the maximum window is 365 days. Use get_transaction_aggregates, get_category_breakdown_aggregates, or get_merchant_breakdown_aggregates for summary analysis instead of fetching raw transactions where possible. Use the transaction_ids filter to retrieve specific transactions identified from a breakdown aggregate tool.
