avenir-mcp

Overview Schema Source Related Servers Discussions Admin

Forecast the balance

forecast_balance

Read-onlyIdempotent

Project YNAB account balances month by month to see when money would run out using scheduled transactions and spending history.

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 (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.

Input Schema

TableJSON Schema

Name	Required	Description
`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

TableJSON Schema

Name	Required	Description
`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.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 29, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare readOnly/idempotent/openWorld, but the description goes well beyond them: it discloses the projection model, the monthly-average deduction for the current month, what is included (scheduled transactions, recurring charges, 3-month averages) and what is deliberately excluded (transfers between projected accounts), plus the explicit assurance 'Changes nothing.' This is unusually rich behavioral disclosure for a read-only tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose and the no-side-effects guarantee are front-loaded, and the dense assumption paragraph is justified by the model's complexity. A couple of sentences (notably the long assumptions list) are run-on, but nothing is filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a multi-parameter forecasting tool, the critical information is the assumption model the agent is implicitly invoking, and the description enumerates every assumption plus what is returned so the user can correct it. The mention of `lowest` and `first_shortfall` slightly overlaps the output schema, but the overall completeness is excellent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: monthly_income 'replacing the income found in the history... and scheduled in YNAB,' one_offs being amounts not already scheduled (which would otherwise be double-counted), and account_ids defaulting to all open on-budget accounts. It clarifies parameter interactions rather than restating the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence states a specific verb and resource plus the concrete outcome: 'Project the balance month by month and say when money would run out.' That is unmistakably a forecasting tool and cannot be confused with the sibling read/report tools such as get_monthly_summary or get_spending_trends.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description sets clear context for when this tool applies (projecting forward when money runs out) and explains how to steer it via overrides like monthly_income, variable_monthly and one_offs. It never names an alternative sibling or states when not to use forecasting versus a historical report, so the routing guidance is clear but not exhaustive.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server