forecast_balance

Generado

Generado desde el código con python -m docsgen; una prueba falla si deja de coincidir. Las descripciones vienen del código y se mantienen en inglés: es el idioma en que las leen los agentes.

Qué hace

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 (a payee with a schedule is projected by it alone; transfers between projected accounts left out), 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: 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. Changes nothing.

Comportamiento

Tipo	solo lectura
Confirmación	no
Deshacer	no
Idempotente	sí
Peticiones a YNAB	4 para el ejemplo de abajo, con la caché vacía

Parámetros

Nombre	Tipo	Obligatorio	Por defecto	Descripción
plan_id	string	sí	—	YNAB plan id or ‘last-used’.
until	string	sí	—	Last month to project, YYYY-MM, at most 24 months ahead.
account_ids	array of string | null	no	null	Accounts to include (from list_accounts); default all open on-budget accounts.
monthly_income	number | null	no	null	Income expected each month, replacing the income found in the history (recurring or average) and scheduled in YNAB; default: what they show.
variable_monthly	number | null	no	null	Monthly spending besides recurring charges (negative); default: the last 3 months’ average.
one_offs	array of object | null	no	null	Expected one-off amounts: {date YYYY-MM-DD, amount, label}; not those already scheduled in YNAB, which are counted.

Devuelve

Campo	Tipo	Descripción
message	string	The conclusion in one sentence, for the agent to relay.
accounts	array of string	Names of the accounts projected together.
start_balance	number	Their total balance today.
assumptions	object	Everything the projection assumed, to check with the user.
assumptions.recurring	array of object	Charges and income found recurring in the history.
assumptions.variable_monthly	number	Monthly spending besides recurring charges, negative.
assumptions.monthly_income	number	Monthly income assumed, besides recurring income.
assumptions.one_offs	array of object	One-off amounts given by the caller.
assumptions.scheduled	array of object	Scheduled transactions of the projected accounts, from tomorrow to the last month; they replace what the history suggests for the same payees. Transfers between the projected accounts are left out.
months	array of object	The projected months.
months[].month	string	Month, YYYY-MM.
months[].start	number	Projected balance on the first day (today’s balance for the current month).
months[].inflows	number	Money expected in during the month.
months[].outflows	number	Money expected out during the month, negative.
months[].end	number	Projected balance at the end of the month.
months[].lowest	number	Lowest projected balance within the month, day by day.
first_shortfall	string | null	First month whose lowest balance is below zero; null if none.

Ejemplo

Argumentos:

{
  "plan_id": "demo-budget",
  "until": "2026-12",
  "monthly_income": 3200
}

Respuesta sobre el presupuesto de demostración:

{
  "message": "The balance stays above zero until 2026-12. This rests on the assumptions listed: check them with the user.",
  "accounts": [
    "Checking",
    "Savings"
  ],
  "start_balance": 4112.66,
  "assumptions": {
    "recurring": [
      {
        "payee": "MARKET FRESH",
        "amount": -182.58,
        "day": 14,
        "months_seen": 3
      },
      {
        "payee": "RAIL CO",
        "amount": -45.0,
        "day": 18,
        "months_seen": 3
      },
      {
        "payee": "STREAMFLIX",
        "amount": -13.49,
        "day": 15,
        "months_seen": 3
      },
      {
        "payee": "TENNIS CLUB - PRELEV",
        "amount": -22.0,
        "day": 20,
        "months_seen": 3
      }
    ],
    "variable_monthly": -68.7,
    "monthly_income": 3200.0,
    "one_offs": [],
    "scheduled": [
      {
        "scheduled_id": "sch-rent",
        "date": "2026-10-03",
        "amount": -950.0,
        "account": "Checking",
        "category": "Rent",
        "payee": "LANDLORD SARL",
        "memo": null,
        "frequency": "monthly",
        "transfer": false
      },
      {
        "scheduled_id": "sch-phone",
        "date": "2026-10-08",
        "amount": -19.99,
        "account": "Checking",
        "category": "Phone",
        "payee": "TELCO MOBILE - PRELEV",
        "memo": null,
        "frequency": "monthly",
        "transfer": false
      },
      {
        "scheduled_id": "sch-power",
        "date": "2026-10-12",
        "amount": -64.2,
        "account": "Checking",
        "category": "Electricity",
        "payee": "POWERCO ENERGIE",
        "memo": null,
        "frequency": "monthly",
        "transfer": false
      },
      {
        "scheduled_id": "sch-insurance",
        "date": "2026-10-20",
        "amount": -420.0,
        "account": "Checking",
        "category": null,
        "payee": "HOMESAFE INSURANCE",
        "memo": null,
        "frequency": "yearly",
        "transfer": false
      },
      {
        "scheduled_id": "sch-rent",
        "date": "2026-11-03",
        "amount": -950.0,
        "account": "Checking",
        "category": "Rent",
        "payee": "LANDLORD SARL",
        "memo": null,
        "frequency": "monthly",
        "transfer": false
      },
      {
        "scheduled_id": "sch-phone",
        "date": "2026-11-08",
        "amount": -19.99,
        "account": "Checking",
        "category": "Phone",
        "payee": "TELCO MOBILE - PRELEV",
        "memo": null,
        "frequency": "monthly",
        "transfer": false
      },
      "… 4 more"
    ]
  },
  "months": [
    {
      "month": "2026-09",
      "start": 4112.66,
      "inflows": 3200.0,
      "outflows": 0.0,
      "end": 7312.66,
      "lowest": 4112.66
    },
    {
      "month": "2026-10",
      "start": 7312.66,
      "inflows": 3200.0,
      "outflows": -1785.96,
      "end": 8726.7,
      "lowest": 6665.72
    },
    {
      "month": "2026-11",
      "start": 8726.7,
      "inflows": 3200.0,
      "outflows": -1365.96,
      "end": 10560.74,
      "lowest": 8089.84
    },
    {
      "month": "2026-12",
      "start": 10560.74,
      "inflows": 3200.0,
      "outflows": -1365.96,
      "end": 12394.78,
      "lowest": 9913.8
    }
  ],
  "first_shortfall": null
}

Errores

• Unknown account(s) {unknown}: use ids from list_accounts.
• until must be the current month or later.
• until must be at most 24 months ahead.
• until must be a month as YYYY-MM, got '{until}'.

Los errores propios de YNAB llegan como Error calling tool '<tool>': YNAB <status>: <detail>.

Ver también

• Planificar