Reports

The reports domain exposes 8 tools.

Tools

reports_balance

Scope tier: read

Sum of bank account balances grouped by currency for the current team. Returns one entry per distinct currency among ENABLED accounts (disabled / connection-paused accounts are excluded). Each entry's amount is the raw stored balance — no FX conversion is applied, so callers should not naively add across currencies. Use this when the user asks 'how much cash do I have', 'show my balances', or anything cash-position related. For a single-number runway calculation in the team's base currency, use reports_runway instead.

No parameters.

reports_burn_rate

Scope tier: read

Monthly burn (total expenses) for the current team over a date range, expressed in the team's base currency. Each row reports a YYYY-MM month label, the absolute sum of negative-amount transactions in that month, and the base currency code. Also returns the simple arithmetic mean across the returned months (average). Cross-currency transactions are excluded so the monthly series is apples-to-apples. Use this when the user asks 'what's my burn', 'how much did I spend per month', or wants a trend chart of expenses.

reports_profit_loss

Scope tier: read

Monthly profit & loss for the current team over a date range — revenue (positive transactions), expense (absolute value of negative transactions), and delta (revenue - expense) per YYYY-MM month. Also returns aggregate totals across the range. All values are in the team's base currency; cross-currency transactions are excluded. Use when the user asks 'show my P&L', 'am I profitable', or wants a profit/expense breakdown by month.

reports_recurring_expenses

Scope tier: read

Heuristically detected recurring expenses for the current team. A counterparty (vendor) is flagged when it appears in at least 3 of the last 6 calendar months with negative-amount transactions in the team's base currency. Returns \{ counterparty, months, avg_amount, currency \} per match, sorted by months desc then avg_amount desc. months is the count of distinct months the counterparty appeared in (max 6). NULL counterparties are skipped. Use when the user asks 'what subscriptions am I paying for', 'recurring bills', or wants to audit ongoing vendor spend.

No parameters.

reports_revenue

Scope tier: read

Monthly revenue for the current team over a date range — the sum of POSITIVE-amount transactions per YYYY-MM month, in the team's base currency. Also returns the grand total. Cross-currency transactions are excluded. This is cash-in revenue (the bank-ledger view); for invoiced revenue by customer use reports_top_customers instead. Use when the user asks 'show revenue', 'how much did I make', or wants a revenue trend chart.

reports_runway

Scope tier: read

Months of runway based on current cash position and average monthly burn over the last 6 calendar months — all expressed in the team's base currency. Returns \{ months, cash, avg_burn, currency \}. months is null (not Infinity) when avg_burn is zero, so downstream JSON renders are safe. Cross-currency cash AND cross-currency expenses are EXCLUDED to keep the ratio coherent. Use when the user asks 'how long can we last', 'what's my runway', or any survival-time question. For per-currency cash positions use reports_balance; for the monthly burn series itself use reports_burn_rate.

No parameters.

reports_spending

Scope tier: read

Spending grouped by transaction category for the current team over a date range. Sums absolute value of negative-amount transactions per category_slug in the team's base currency, sorted by amount descending. Uncategorized transactions are EXCLUDED from both the breakdown and the total (so the total matches the sum of the array). Cross-currency transactions are excluded. Use when the user asks 'where is my money going', 'spending by category', or wants a category-level expense breakdown. For a time-series view use reports_burn_rate.

reports_top_customers

Scope tier: read

Top customers by paid invoice revenue for the current team, sorted descending. Groups by (customer_id, currency) so a customer billed in two currencies appears as two rows — currencies are kept separate to avoid silent FX mixing. Only status = 'paid' invoices contribute. Date range filters on paid_at (cash receipt date); omit both from and to for all-time totals. customer_name is denormalized from the customers table; if the invoice references a deleted customer the name will be null. Use when the user asks 'who are my best customers', 'top revenue contributors', or 'biggest accounts'.