Forecast the balance
forecast_balanceProject your budget balance month by month and see when money would run out. Estimates scheduled bills, recurring charges, and income to flag the first shortfall.
Instructions
Project the balance month by month and say when money would run out.
Starts from today's balance of the open on-budget accounts (or those given).
For the current month, what was already spent or received since the 1st is
deducted from the monthly averages, so only what is left is projected.
Assumes, and returns as assumptions so the user can correct them: YNAB's
scheduled transactions on their dates, whatever their frequency, a yearly bill
included, charges that recur in the last 4 months (same payee, stable amount),
the average of all other spending over the last 3 months, and what you pass.
A payee with a schedule is projected by that schedule alone, and transfers
between the projected accounts are left out. What you pass is the expected
monthly income (default: the last 3 months' non-recurring inflows, which may
include one-off money such as capital injections) and one-off amounts such as
a tax bill (negative) or a refund (positive). Amounts in currency units.
lowest is the lowest point within a month; first_shortfall is the first
month it goes below zero. For a month already gone use get_monthly_summary, or
get_spending_trends to compare several; for how long today's money would last
with no income at all, get_runway. Changes nothing.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"plan_id": "<plan_id>",
"until": "<until>"
},
"name": "forecast_balance"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| until | Yes | Last month to project, YYYY-MM, at most 24 months ahead. | |
| plan_id | Yes | YNAB plan id or 'last-used'. | |
| one_offs | No | Expected one-off amounts: {date YYYY-MM-DD, amount, label}; not those already scheduled in YNAB, which are counted. | |
| account_ids | No | Accounts to include (from list_accounts); default all open on-budget accounts. | |
| monthly_income | No | Income expected each month, replacing the income found in the history (recurring or average) and scheduled in YNAB; default: what they show. | |
| variable_monthly | No | Monthly spending besides recurring charges (negative); default: the last 3 months' average. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| months | Yes | The projected months. | |
| message | Yes | The conclusion in one sentence, for the agent to relay. | |
| accounts | Yes | Names of the accounts projected together. | |
| assumptions | Yes | Everything the projection assumed, to check with the user. | |
| start_balance | Yes | Their total balance today. | |
| first_shortfall | Yes | First month whose lowest balance is below zero; null if none. |