avenir-mcp

Overview Schema Source Related Servers Discussions Admin

Net worth month by month

get_net_worth_trend

Read-onlyIdempotent

Tracks monthly net worth, assets, and debts so you can see whether debt is falling and how net worth changes over up to 24 months.

Instructions

Assets, debts and net worth at the end of each month, to see debts go down.

Use it for "is my debt going down?", "am I paying off my loans?" or "how did my net worth change over the year?". Every account counts, tracking ones included: credit cards, lines of credit, loans, mortgages and other liabilities are debts; every other account is an asset. A closed account counts for the months it still had a balance. months_count counts back from the current month, included, so 1 gives this month alone and the default 12 the year up to it, however long the plan has existed. Each month is read on its last day, the current one included: today's balance less the transactions dated after that day, so this month already counts what is entered for the days left. Amounts in currency units; debts are negative, as YNAB shows them, and net_worth is assets plus debts. For each account's balance today use list_accounts; for the months ahead, forecast_balance. Two YNAB requests: accounts, transactions; 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>"
    },
    "name": "get_net_worth_trend"
  }
}

Input Schema

Name	Required	Description	Default
`plan_id`	Yes	YNAB plan id or 'last-used'.
`months_count`	No	Number of months to show, the current one included, 1 to 24 (default 12).

Output Schema

Name	Required	Description
`change`	Yes	Last minus first: positive when the net worth grew.
`months`	Yes	One entry per month, oldest first.
`accounts`	Yes	Names of the accounts counted: the open ones, and the closed ones that still had a balance at one of these month ends.
`last_net_worth`	Yes	Net worth at the end of the last month shown: today's.
`first_net_worth`	Yes	Net worth at the end of the first month shown.

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.5.0Oct 2, 2026

TDQS

A4.4/5.0

Behavior3/5

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

Annotations already establish readOnly, idempotent, openWorld, so the safety profile is covered. The description nonetheless adds genuinely non-obvious behavior: which account types count as debts, that closed accounts count while they had a balance, that each month is valued on its last day net of later-dated transactions, and the sign convention. The cost disclosure ('Two YNAB requests: accounts, transactions') is useful operational context.

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?

Front-loaded with the core behavior and the usage questions before the detailed accounting rules. It runs long and the clause about the current month's prorated balance is dense, but nearly every sentence carries distinct information rather than 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 two-parameter, read-only analytics tool with an output schema, the description covers everything an agent needs: scope, account inclusion rules, month-end valuation, sign convention and net worth composition. Return-value formatting is correctly left to the output schema.

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 earns more by defining the counting semantics of months_count: it counts back from the current month inclusive, so 1 is this month alone and 12 is a year, regardless of how long the plan has existed. That is interpretation the schema does not supply.

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?

Opens with a specific verb-and-resource statement: assets, debts and net worth at each month end, for the purpose of watching debt decline. It is immediately distinguishable from list_accounts (today's balances) and forecast_balance (future months), both of which are named explicitly.

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?

Gives concrete triggering questions ('is my debt going down?', 'am I paying off my loans?') plus explicit routing: list_accounts for each account's balance today, forecast_balance for months ahead. Both the when and the when-not are spelled out.

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