Skip to main content
Glama
Sign In
YNAB MCP Server

YNAB MCP Server

by oliverames
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

Get Budget Health

get_budget_health
Read-onlyIdempotent

Calculates a budget health snapshot from YNAB months and accounts, summarizing savings rate, age of money, Ready to Assign, overspends, and card funding with green/yellow/red status.

Instructions

Budget snapshot: savings rate, age of money, Ready to Assign, overspends, card funding; green/yellow/red. Uses month/accounts and trailing-3-month income/spending (~4 requests). Defaults, not YNAB rules: savings 20%+ green, underfunded card debt red, overspends yellow.

Input Schema

NameRequiredDescriptionDefault
budgetIdNo
incomeCategoryIdsNoExplicit income IDs if category metadata is ambiguous.

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv6.1.0
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • removedInput schema / properties / budgetId / description
      Removed value: -"Budget ID (uses default if not provided)"
    • addedInput schema / properties / incomeCategoryIds
      Added value: +{
+  "description": "Explicit income IDs if category metadata is ambiguous.",
+  "items": {
+    "type": "string"
+  },
+  "maxItems": 10,
+  "minItems": 1,
+  "type": "array"
+}
    • changedOutput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
  2. Changed1 schema field changedv5.4.0
    • removedOutput schema / properties / result / description
      Removed value: -"Structured result returned by Get Budget Health."
  3. Addedv5.2.0

TDQS

A3.7/5.0
Behavior4/5

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

Annotations already cover safety (readOnly, idempotent, non-destructive), and the description adds real value on top: an estimated cost of ~4 requests and the exact data windows (month/accounts, trailing three months) used to compute the score. The explicit disclaimer that the green/yellow/red thresholds are 'Defaults, not YNAB rules' is important interpretive context an agent would otherwise get wrong.

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?

Two dense sentences, front-loaded with the output contents before the cost and threshold caveats. Semicolon-packed telegraphy costs a little readability, but no clause is filler.

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?

For a composite analytics tool with an output schema and full safety annotations, the description supplies the essential missing pieces: data sources, request cost, and scoring heuristics. Remaining gaps are the budgetId default and the fact that it references 'month' despite having no month parameter, which could mildly confuse an agent.

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

Parameters3/5

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

Schema coverage is 50%: incomeCategoryIds is documented in-schema, but budgetId has no description and zero required parameters, so the default-scoping behavior is unclear. The description's mention of 'Defaults' refers only to score thresholds, not to which budget is used when budgetId is omitted, so it does not compensate for the gap.

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?

Names a specific artifact (a budget health snapshot) and enumerates exactly what it contains: savings rate, age of money, Ready to Assign, overspends, card funding, plus a green/yellow/red rating. That metric set distinguishes it from siblings like get_income_expense_summary or get_spending_trends, though it never names those alternatives explicitly.

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?

'Uses month/accounts and trailing-3-month income/spending (~4 requests)' hints at what it aggregates, so an agent can infer it is a composite diagnosis rather than a raw data fetch. But there is no explicit 'use this when...' or routing away from sibling analytics tools such as get_spending_trends or audit_credit_card_payments.

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

Deploy Server

Other Tools