YNAB MCP Server

Plan Summary

ynab_plan_summary

Read-only

Get a summary of the plan for a specific month highlighting overspent categories that need attention and categories with a positive balance that are doing well.

Instructions

Get a summary of the plan for a specific month highlighting overspent categories that need attention and categories with a positive balance that are doing well. Set budgetVsActuals to also compare assigned with actual spending that month: budgeted, activity, balance, variance (budgeted plus activity; below zero means more was spent than assigned) and percent used for every visible category, with subtotals per category group and overall totals, which leave out Credit Card Payments.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "ynab_plan_summary"
  }
}

Input Schema

Name	Required	Description
`month`	No	The plan month in ISO format (e.g. 2016-12-01). The string 'current' can also be used to specify the current calendar month (UTC)
`planId`	No	The plan ID (optional, defaults to YNAB_PLAN_ID; budgetId is a deprecated alias)
`budgetId`	No	Deprecated alias of planId (still accepted)
`budgetVsActuals`	No	Add a budget_vs_actuals block comparing assigned with actual spending per category for the month, with group subtotals (default: false)

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.6.0Oct 22, 2026

addedInput schema / properties / budgetVsActuals

Added value: +{
+  "anyOf": [
+    {
+      "description": "Add a budget_vs_actuals block comparing assigned with actual spending per category for the month, with group subtotals (default: false)",
+      "type": "boolean"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Add a budget_vs_actuals block comparing assigned with actual spending per category for the month, with group subtotals (default: false)"
+}

Addedv0.3.0Sep 22, 2026

TDQS

A3.8/5.0

Behavior4/5

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

Annotations already declare a read-only, non-destructive operation. The description adds useful behavioral context beyond that: it explains the default summary focus and details what appears in the optional budgetVsActuals block, including the fact that overall totals exclude Credit Card Payments.

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 description is dense but front-loaded and every sentence carries useful information about scope or output. It avoids filler, though the main sentence is long and could be slightly easier to scan.

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

Completeness4/5

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

With no output schema and annotations covering safety, the description does most of the work by explaining the default summary behavior and the optional budgetVsActuals output structure. It leaves some detail unspecified, such as the exact shape of the default summary, but it is complete enough to call the tool correctly.

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 schema already documents the parameters. The description still adds meaningful semantics for budgetVsActuals, clarifying the fields returned and defining variance as budgeted plus activity, where below zero means overspending.

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

Purpose4/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: get a plan summary for a month, with emphasis on overspent and positive-balance categories. It is clear what the tool does, but it does not explicitly differentiate itself from siblings such as ynab_budget_summary or ynab_spending_by_category.

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

Usage Guidelines3/5

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

The description implies usage by mentioning overspent categories and positive balances, and it gives a condition for enabling budgetVsActuals. However, it does not say when to use this tool versus alternatives or when not to use it.

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