avenir-mcp

Overview Schema Source Related Servers Discussions Admin

Month summary

get_monthly_summary

Read-onlyIdempotent

Review any month's income, budgeted, spent, and Ready to Assign totals, plus overspent categories, so you can see where money went at a glance before planning adjustments.

Instructions

A month at a glance: income, budgeted, spent, Ready to Assign, overspent categories.

Use it first to review a month. Give month as the first day of a month, YYYY-MM-01; any other day is refused. 'current' is the month in progress: its figures are partial, and already count what is entered for the days left. Amounts in currency units; activity is negative for spending. Only overspent categories are listed: for every category use get_category_balances; for the months before, get_spending_trends; for the months ahead, forecast_balance. One YNAB request; 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_monthly_summary"
  }
}

Input Schema

Name	Required	Description	Default
`month`	No	'YYYY-MM-01' or 'current'.	current
`plan_id`	Yes	YNAB plan id or 'last-used'.

Output Schema

Name	Required	Description
`month`	Yes	First day of the month, YYYY-MM-01.
`income`	Yes	Money received in the month and assigned to Ready to Assign.
`activity`	Yes	Total spent (negative) and received in categories during the month.
`budgeted`	Yes	Total assigned to categories in the month.
`overspent`	Yes	Categories whose available balance is negative this month.
`age_of_money`	Yes	Days between receiving money and spending it, as YNAB computes it; null when unknown.
`ready_to_assign`	Yes	Money not yet given a job; negative when more was assigned than received.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 29, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already declare readOnly/idempotent/openWorld, but the description adds substantial context: a single YNAB request, 'current' returns partial figures that still count entered future days, amounts are currency units with negative activity for spending, and only overspent categories appear. It also warns that non-first-of-month dates are refused, a real behavioral constraint not in the annotations.

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 payload summary, then routing, then format rules, then output semantics – a logical order with no filler sentences. It is dense but each clause carries information; only the 'changes nothing' phrasing slightly restates the readOnly annotation.

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, return values need not be explained, and everything else an agent needs is here: date format strictness, 'current' semantics, sign convention for activity, the overspent-only scope, alternatives, and request cost. Nothing material is missing for a simple two-parameter read tool.

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% and the schema already documents both parameters, so a baseline 3 applies, but the description adds genuine meaning: the month must be the first day of the month, other days are refused, and 'current' means the in-progress month with partial figures. That goes beyond the schema's terse enum-like hint.

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?

States a specific verb and resource plus exactly what the payload contains (income, budgeted, spent, Ready to Assign, overspent categories), and explicitly contrasts with get_category_balances, get_spending_trends and forecast_balance. An agent can pick this out from the sibling list 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?

'Use it first to review a month' gives an explicit entry-point rule, and alternatives are named with their selecting conditions: get_category_balances for every category, get_spending_trends for prior months, forecast_balance for future months. When-to-use and when-not-to-use are both covered.

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