Cash Flow Frog

Clear a sales order's split collection schedule, reverting to a single expected collection date. Idempotent: succeeds even when the sales order has no split. Returns the updated sales order.

clearSalesOrderCollectionSchedule

Returns side-by-side cash flow forecasts for two or more scenarios over the same period. Use this whenever the user wants to compare scenarios — "best vs worst case", "base case vs new hire scenario", or "which scenario leaves us with more cash?". Provide 2–5 scenario IDs. Returns one forecast per scenario in the same order, each with opening/closing balance, total inflows/outflows, and per-period breakdown. Use listScenarios first to find the scenario IDs to compare.

compareScenariosForPeriod

Create a new cash flow category (shown in the app UI as a new "Account Type"). The name must be unique within the company. Pick the type carefully — it determines which cash-in / cash-out bucket the category shows up under in the cash flow statement: - CASH_IN for income categories (e.g. "Sales", "Refunds Received") - CASH_OUT for expense categories (e.g. "Payroll", "Rent") - ANY only when the category genuinely applies to both directions

createCashFlowCategory

Create a new cash flow projection. REQUIRED fields: - account: the account dimension (use listDimensionOptions with type=ACCOUNT to find options) - date: start date in YYYY-MM-DD format - recurrenceType: NONE (one-time), DAILY, WEEKLY, BIWEEKLY, SEMIMONTHLY, MONTHLY, QUARTERLY, SEMIANNUAL, or ANNUAL - amount: positive for income, negative for expense (required unless 'rule' is provided) - secondDayOfMonth: required when recurrenceType=SEMIMONTHLY - dimensions: MUST include a CUSTOMER dimension for income (positive amount) or a VENDOR dimension for expense (negative amount). Use listDimensionOptions with type=CUSTOMER or VENDOR to find options, or pass value='OTHER' if no specific vendor/customer applies. Example expense: [{"dimensionType": "VENDOR", "value": "vendor-api-id", "name": "Vendor Name"}] Example income: [{"dimensionType": "CUSTOMER", "value": "customer-api-id", "name": "Customer Name"}] For common projection creation, prefer addRecurringExpense or addRecurringIncome — they handle dimensions automatically. OPTIONAL fields: - recurrenceValue: positive integer multiplier on the recurrence interval (default 1). Combined with recurrenceType to express custom intervals — e.g. recurrenceType=WEEKLY + recurrenceValue=3 means every three weeks; recurrenceType=MONTHLY + recurrenceValue=2 means every two months. Ignored when recurrenceType=NONE. - active: whether the projection is included in cash flow forecasts (default true). Set to false to create the projection in an excluded/disabled state. - details: description/label (strongly recommended) - endDate: last recurrence date (required for recurring projections) - additional entries in dimensions: DEPARTMENT, LOCATION, PROJECT, CLASS - trend: growth/decline per recurrence (mutually exclusive with rule) - rule: dynamic amount rule (mutually exclusive with amount and trend) - notes: list of notes The category is automatically derived from the account — do not set it manually.

createProjection

Create a new cash flow scenario for a company. Use this to model different financial situations with different projections. For example, create a "New Office Lease" scenario to see how signing a lease would affect the company's cash position, without changing the base scenario.

createScenario

Delete a cash flow category. Fails if the category is still referenced by any account mapping or projection — clear those references first (use setAccountCategory / clearAccountCategory on the affected accounts, and update or delete the affected projections). Categories synced from an accounting system are soft-disabled instead of hard-deleted, so a re-sync will not resurrect them as fresh entries.

deleteCashFlowCategory

Delete a cash flow projection and all its occurrences. This is irreversible. To stop a recurring projection from a specific date without deleting past occurrences, use updateProjection to set endDate to today instead. Do NOT call this for projections where recurringTemplate=true. Those are mirrors of accounting software recurring transaction templates and cannot be deleted from CFF. Inform the user and suggest they manage the template in their accounting software, or use company settings to exclude all recurring template projections from the forecast.

deleteProjection

Delete a cash flow scenario and all of its projections. This is irreversible. The company's base/default scenario cannot be deleted.

deleteScenario

Scans the cash flow forecast and identifies all contiguous periods where the projected balance drops below a threshold (default: zero). Returns each at-risk date range with its minimum balance, along with overall minimum and cash runway in days. Use this to answer questions like: - "Will we ever run out of cash?" - "Are there months where our balance goes negative?" - "How many days of runway do we have?" - "When is the riskiest point in our cash flow?" If riskPeriods is empty, the balance stays above the threshold for the entire scanned period — no cash flow risk was detected.

detectNegativeBalancePeriods

Export a saved custom AI report with live company data and return a presigned download link. The link is valid for 15 minutes and points to the generated XLSX or CSV file. Call listCustomReports first to discover available report IDs and their baked-in date ranges. If the report has a dateRange preset (e.g. NEXT_N 4 weeks), compute the actual calendar dates from today before calling this tool — do not leave startDate/endDate empty. If the export fails with a message about the data set being too large, tell the user. For reports without aggregationDimensions, suggest a shorter date range. For reports with aggregationDimensions, use the two-stage flow instead: prepareCustomReportExport → finalizeCustomReportExport.

exportCustomReport

Stage 2 of the two-stage MCP export flow. Receives the structured rows you produced from cashFlowData[], builds the final XLSX or CSV file, uploads it to S3, and returns a presigned download link valid for 15 minutes. You must call prepareCustomReportExport first to obtain the exportToken. The exportToken expires 15 minutes after it was issued — finalize within that window. Row format: - headers: column names in order, matching the columns in your processingPrompt output. - rows: one inner list per data row; values must be in the same column order as headers. - Use JSON numbers (not strings) for numeric cells so Excel formats them correctly. Example: headers: ["Project", "Week 1 In", "Week 1 Out", "Net"] rows: [["Alpha", 15000.0, 3200.0, 11800.0], ["Beta", 9000.0, 1100.0, 7900.0]]

finalizeCustomReportExport

Generate a standard PDF cash flow report and return a one-time download link. The link is valid for 15 minutes. The PDF is visual — it contains embedded bar and line charts (OVERVIEW, CASH_BALANCE pages) alongside tables. It is the only output format that produces charts or graphs; CSV/XLSX exports from saveCustomReport/ exportCustomReport are tabular only. WHEN TO CALL: Immediately when the user asks for a PDF, a chart, a graph, or any visual summary of cash flow — e.g. "give me a PDF of my cash flow", "show me a graph of my next 6 months", "I want a chart", "generate a report I can share", "show me outflows for October as a PDF". Do not analyse intent first — just call this tool. When the user asks for a graph or chart and does not specify Excel, this is the correct tool; explain the output is PDF after the link is ready. THIS TOOL FETCHES ALL ITS OWN DATA INTERNALLY. Do NOT call getCashFlowBreakdown, listBills, getCashFlowForecast, or any other data tool before calling this one. The only pre-flight calls that may be needed are listCompanies and listScenarios if you do not already have companyId and scenarioId. Use cashFlowType to scope the report: - ANY — full report with both inflows and outflows (default) - CASH_IN — only the inflow-related pages and data - CASH_OUT — only the outflow-related pages and data The report has 8 standard pages that can each be individually included or excluded: COVER, OVERVIEW, CATEGORY_BREAKDOWN, CASH_BALANCE, CASH_IN_BREAKDOWN, CASH_OUT_BREAKDOWN, CUSTOMER_INSIGHTS, NOTES All pages are included by default — only set pages when the user wants to hide specific sections. grouping controls the time granularity: DAY — day-by-day (up to ~3 months), WEEK — week-by-week (1–6 months), MONTH — month-by-month (6–18 months), QUARTER — quarter-by-quarter (multi-year) topLevelGroupBy controls how cash flows are grouped in the breakdown: ACCOUNT_TYPE (default), QB_CLASS, XERO_TRACKING_CATEGORY, DEPARTMENT, LOCATION, PROJECT DO NOT use this tool for custom column layouts, Excel/CSV exports, AR/AP aging reports, or any report requiring a user-defined data structure — use saveCustomReport + exportCustomReport for those.

generateCashFlowReportPdf

Return a high-level accounts-payable summary for the scenario: total open balance, total overdue balance, open and overdue bill counts, the age of the oldest overdue bill (in days), and the single largest open bill. Use this as a quick health-check for the AP book — "how much do we owe and how much is past due?" — before drilling into individual bills.

getAPSummary

Return a high-level accounts-receivable summary for the scenario: total open balance, total overdue balance, open and overdue invoice counts, the age of the oldest overdue invoice (in days), and the single largest open invoice. Use this as a quick health-check for the AR book — "how much do customers owe us and how much is overdue?" — before drilling into individual invoices.

getARSummary

Get a single account by its id, including its current category mapping. Use this to confirm an account's classification before or after a setAccountCategory / clearAccountCategory call. IMPORTANT: accountId must come from listAccounts (the `id` field). Never use a groupId from getCashFlowBreakdown — those are category/dimension identifiers, not account ids.

getAccount

Get the projected (forecast) total bank balance for a company on a specific future date, based on a scenario's projections added to the current actual bank balance. This is not the live bank balance — it is the forecasted balance after applying all projected cash flows up to that date. Use this to answer questions like: - "What will our bank balance be on [date]?" - "Will we have enough cash to cover the lease payment on [date]?" - "What's the projected balance at end of quarter?" Returns the projected total balance across all tracked bank accounts.

getBankBalance

Get a single bill by its id, including its expected payment date and any split payment schedule.

getBill

Get a categorized cash flow breakdown for a company and scenario over a date range. Returns inflows and outflows split by a chosen axis (category by default), with optional drill-down detail. Use this when getCashFlowForecast (which only returns flat per-period totals) isn't enough. Typical questions this answers: - "Which categories made up most of last quarter's expenses?" - "Which customers drove Q3 inflows?" (groupBy=CATEGORY, drillDownBy=CUSTOMER_OR_VENDOR) - "Show me payroll spend by department." (groupBy=DEPARTMENT) - "Break down rent by location." (groupBy=LOCATION) For a forecast scoped to a specific dimension (e.g. one project only), use getCashFlowForecast with dimensionFilters instead. Defaults: groupBy=CATEGORY, drillDownBy=NONE. groupBy controls the top-level grouping axis (what each row in the output represents). drillDownBy controls the secondary axis inside each group (sub-rows). These are independent: groupBy=CATEGORY + drillDownBy=CUSTOMER_OR_VENDOR shows each category broken down by who paid/was paid. Output shape: - `periods[]`: per-period objects (periodStart, totalInflows, totalOutflows, closingBalance, isHistorical=true if entirely past). - `cashIn` / `cashOut`: each has `total`, `totalsByPeriod`, and `groups[]`. Each group has `label`, `groupId` (null when unclassified), `total`, `totalsByPeriod`, and `drillDown[]` (omitted when drillDownBy=NONE). Outflow values are negative. - `drillDown[].id` is populated only when drillDownBy=ACCOUNT. Cross-reference: groupId on a CATEGORY group is the same id used in listCashFlowCategories / setAccountCategory. Drill-down account ids match the id in listAccounts. For individual transaction rows within a category or drill-down group, use listTransactions. IMPORTANT: groupId values in this response are category/dimension identifiers — NOT account ids. Never pass a groupId to getAccount or setAccountCategory as an accountId. Account ids come exclusively from listAccounts.

getCashFlowBreakdown

Get a single CashFlowCategory by id.

getCashFlowCategory

Primary tool for cash flow analysis. Get a cash flow forecast for a scenario over a date range, grouped by the chosen time granularity. Combines real bank account balances with the scenario's projected cash flows — including AR invoices, AP bills, estimates, sales orders, purchase orders, and manual projections — to show how the cash position is expected to change over time. Use this to answer questions like: - "What will our cash balance look like next month?" (MONTHLY grouping) - "When will we hit our lowest cash point this quarter?" (WEEKLY or DAILY grouping) - "Are we going to run out of cash before our next big payment comes in?" (DAILY grouping) - "Give me a quarterly cash flow overview for the rest of the year" (QUARTERLY grouping) Choose grouping based on the question: - DAILY — precise day-by-day view, best for short ranges (up to ~3 months) - WEEKLY — week-by-week view, good for 1–6 month ranges - MONTHLY — month-by-month view, good for 6–18 month ranges - QUARTERLY — quarter-by-quarter view, best for multi-year ranges Use dimensionFilters to scope the forecast to a specific customer, vendor, project, or other dimension. For a breakdown by category or dimension group, use getCashFlowBreakdown instead. For individual transaction rows within any period, use listTransactions. Returns: opening/closing balances for the full period, total inflows/outflows, and a per-period breakdown with each period's balance and cash movements.

getCashFlowForecast

Returns a cash health snapshot: current bank balance, projected balances at 30/60/90 days, the lowest projected balance within the horizon, and the first date the balance goes negative (if any). Use this as the starting point for any question about current or near-term cash position. Combines real bank account balances with scenario projections. Use this to answer questions like: - "What is our current cash situation?" - "How much cash will we have in 30/60/90 days?" - "Are we heading toward a cash crunch?" - "What's the lowest our balance will get this quarter?" For detailed risk analysis — exact periods when balance goes negative, cash runway in days — use detectNegativeBalancePeriods instead.

getCashPosition

Returns an Actual-vs-Plan variance comparison for every cash flow category over a date range. For each category, surfaces the actual total, the planned total (what was forecast when the period was still in the future), the variance (actual − planned), and the variance as a percentage of the plan. Use this when the user wants to know: - "Which categories came in over or under budget last quarter?" - "How did our payroll compare to plan in Q1?" - "Where did actual inflows beat or miss our forecast?" - "Give me a budget vs actual breakdown for last month." - "What was the biggest variance category this year?" Variance sign convention (consistent for both cashIn and cashOut): - Positive variance → favorable: actuals exceeded plan for cashIn, or spending was below plan for cashOut (cashOut values are negative, so actual less negative = positive). - Negative variance → unfavorable: cashIn below plan, or cashOut above plan (overspent). For meaningful results, use a historical (or mostly historical) date range — plan comparison is only available where isHistorical=true periods exist. Future periods contribute actuals but will have null planned values. grouping controls the time granularity of per-period arrays. For month-over-month analysis use MONTHLY; for week-by-week use WEEKLY. Match the granularity to the range length. Output shape: - periods[]: period headers with periodStart, periodEnd, isHistorical (true = past) - cashIn / cashOut: each has aggregate actual, planned, variance, variancePct and categories[] sorted by absolute variance (largest deviations first). Each category has categoryName, categoryId, actual, planned, variance, variancePct, plus per-period arrays: actualByPeriod, plannedByPeriod, varianceByPeriod. varianceByPeriod entries are null for future periods (no plan comparison available). - categoryId can be passed as groupId to getCashFlowBreakdown for drill-down detail (e.g. to see which customers or vendors drove the variance in a specific category).

getCategoryVariance

Returns all company forecast settings grouped by area: projections, invoices, bills, estimates, salesOrders, purchaseOrders, cashBalance, and advanced. Call this before updateCompanySettings to inspect the current state.

getCompanySettings

Get a single estimate by its id, including its expected collection date and any split collection schedule.

getEstimate

Get a high-level summary of all open estimates: total open amount, count, expiring-soon count (estimates expiring within 30 days), and the largest estimate. Use this as a quick health-check for the estimates pipeline — "how much is in open quotes?" — before drilling into individual estimates.

getEstimateSummary

Return the accounting software integration status for a company: which platform is connected (e.g. XERO, QUICKBOOKS), current connection status (CONNECTED, DISCONNECTED, ERROR, PENDING), timestamps of the last sync attempt and last successful sync, and any error message when the connection is in an error state. Call this first when a user asks whether their data is up to date, why their forecast looks stale, or whether there are any sync problems — before querying invoices, bills, or forecasts that may reflect outdated data.

getIntegrationStatus

Get a single invoice by its id, including its expected collection date and any split collection schedule.

getInvoice

Returns a URL for the user to open in their browser to set up or reconnect their accounting software integration with Cash Flow Frog. Call this when listCompanies returns an empty list, or when getIntegrationStatus returns DISCONNECTED or ERROR for any company. No parameters are needed — the server determines the appropriate URL from the authenticated user's context and integration state. Present the returned url as a clickable link with the message as context. After the user confirms they have completed the flow, call listCompanies again to verify. Returns: url (the link to present), action ("setup" | "reconnect" | "connected"), message (human-readable explanation to show alongside the URL).

getOnboardingUrl

Get a single cash flow projection by its id. Use this to retrieve full details of a specific projection after finding its id from listProjections.

getProjection

Get a single purchase order by its id, including its expected payment date and any split payment schedule.

getPurchaseOrder

Get a high-level summary of all open purchase orders: total open amount, count, and the largest purchase order. Use this as a quick health-check for outstanding purchase commitments — "how much in open purchase orders has not been billed yet?" — before drilling into individual purchase orders.

getPurchaseOrderSummary

Returns the instructions for the current step of the custom report intake flow. Call with step=1 to begin, then step=2 when you are ready to draft and save.

getReportBuilderStep

Get a single sales order by its id, including its expected collection date and any split collection schedule.

getSalesOrder

Get a high-level summary of all open sales orders: total open amount, count, and the largest sales order. Use this as a quick health-check for the sales order pipeline — "how much in open orders has not been invoiced yet?" — before drilling into individual sales orders.

getSalesOrderSummary

List the company's chart of accounts together with their current cash flow category mapping. Use this to see how accounts are classified, find unmapped accounts, or locate a specific account by name. The `categoryId` / `categoryName` fields are the account's user-facing "Account Type" (its CashFlowCategory mapping). A null value means the account is unmapped — its transactions fall into the default "OTHER" bucket. Reassign with setAccountCategory. The raw `type` / `subType` / `classification` fields are internal source-accounting-system values; do not report them to the user as the account's "type". Filters are optional and combine (AND).

listAccounts

List all bank and financial accounts for a company, including their current balances. These are the accounts that Cash Flow Frog tracks and forecasts. Use this to understand the company's current liquidity position and to answer questions like "what is our current total cash balance?". Returns: id, name, type (e.g. Bank, CreditCard), subType (e.g. Checking, Savings), balance, currencyCode, and whether the account is active.

listBankAccounts

List the company's open bills (accounts payable) for a scenario — money the company owes its vendors. Returns only open (unpaid) bills. Each bill includes its open balance, due date, the expected payment date that drives the cash flow forecast, an overdue flag, and any split payment schedule. Each bill's expectedPaymentDate determines when it appears in the cash flow forecast — if null, the dueDate is used as a fallback. Use setBillExpectedPaymentDate to update when payment is actually planned. For aggregate totals without individual rows, use getAPSummary. Results are sorted by expected payment date. Filters are optional and combine (AND). Use overdueOnly=true to focus on bills already past their due date. Use date range filters to answer questions like "what bills are due this month?" Use minAmount / maxAmount to filter by open balance — e.g. minAmount=200 returns only bills where the outstanding balance is at least 200 (in the company's home currency).

listBills

List the cash flow categories defined for a company. Categories are the buckets that accounts (and therefore transactions and projections) are classified under in cash-in and cash-out reports. NOTE: the app UI calls a cash flow category an "Account Type". If a user asks to "list account types", this is the tool to use. (The `type` field on an Account is a separate internal accounting-system value — not what users mean by "account type".) Each category has a `type` of its own (its cash flow direction): - CASH_IN — categories used for income (positive cash flow) - CASH_OUT — categories used for expenses (negative cash flow) - ANY — categories that can apply to either direction Disabled categories are hidden by default; pass includeDisabled=true to see them.

listCashFlowCategories

REQUIRED FIRST STEP — call this before any other tool. Lists all companies the authenticated user has access to. The `id` field from the response is the companyId required by nearly every other tool. Users typically have one company, but may have multiple. After calling this, call listScenarios to get the available scenarios. Returns: id, name, currencyCode, timezone, accountingSoftware.

listCompanies

List all custom AI report definitions for the company. Returns saved report definitions that can be exported with live company data. Use this to discover available reports before exporting one.

listCustomReports