avenir-mcp

Overview Schema Source Related Servers Discussions Admin

Savings rate month by month

get_savings_rate

Read-onlyIdempotent

Calculate your monthly savings rate from YNAB income and spending. Get figures for income, spending, saved amounts, and savings percentage.

Instructions

How much of the income was kept, month by month: income, spending, saved, rate.

Use it for "what's my savings rate?", "how much do I put aside each month?" or "am I saving more than last spring?". Income is money in categorised to Ready to Assign on the budget accounts; starting balances and transfers are not income. Spending is money out of the budget accounts less refunds (money in categorised to a spending category); transfers between budget accounts are left out, a transfer to a tracking account holding an asset (savings, investments) is saved, a transfer to a tracking loan is spending. Saved is income plus spending; rate is saved over income, in percent, null for a month without income. Complete months only, from the budget's first transaction. Relay the notes with the figures. Amounts in currency units, spending negative. For spending per category use get_spending_trends. Three YNAB requests: accounts, categories, transactions; changes nothing.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`plan_id`	Yes	YNAB plan id or 'last-used'.
`months_count`	No	Complete months to measure, before the current one, 1 to 24 (default 6).

Output Schema

TableJSON Schema

Name	Required	Description
`rate`	Yes	Saved over income for the whole period, in percent to one decimal; null when nothing came in.
`notes`	Yes	How the figures were counted, to tell the user.
`saved`	Yes	Saved over the period: income plus spending.
`income`	Yes	Income over the period.
`months`	Yes	The complete months measured, oldest first.
`message`	Yes	The conclusion in one sentence or two, for the agent to relay.
`spending`	Yes	Spending over the period, negative.
`best_month`	Yes	The month with the highest rate, YYYY-MM; null when no month had income.
`worst_month`	Yes	The month with the lowest rate, YYYY-MM; null when no month had income.
`average_saved`	Yes	Saved per month, on average over the months measured.
`moved_to_tracking`	Yes	Money moved to tracking accounts that hold an asset over the period, part of saved.

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.5.0Oct 2, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Beyond the read-only/idempotent annotations, it discloses genuinely load-bearing behavior: how 'income' and 'spending' are defined, that transfers between budget accounts are excluded, that transfers to tracking asset vs loan accounts count as saved vs spent, that months with no income yield a null rate, that only complete months from the first transaction count, and that it fires three requests and changes nothing.

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 output shape and purpose are front-loaded, and the definition sentences (income/spending/transfer edge cases) each prevent a real misreading. It is dense and long, but nearly every clause earns its place; slightly tighter phrasing would be ideal.

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?

With an output schema present and 100% parameter coverage, the remaining burden is the semantic contract, and the description supplies it fully: field definitions, unit/sign conventions, null handling, and the 'relay the notes with the figures' instruction for presenting results.

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: 'Complete months only, from the budget's first transaction' constrains what months_count actually counts, and 'Amounts in currency units, spending negative' clarifies the output sign convention rather than leaving it to inference.

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 description states a specific verb and resource (compute savings rate from income/spending/saved), enumerates the exact fields returned ('income, spending, saved, rate'), and explicitly distinguishes itself from the sibling get_spending_trends. An agent can tell precisely what this returns without opening the schema.

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

Usage Guidelines5/5

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

It gives concrete trigger phrasings ('what's my savings rate?', 'am I saving more than last spring?') and names the alternative with the condition that selects it ('For spending per category use get_spending_trends'). When-to-use and when-to-use-something-else are both covered.

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