Skip to main content
Glama
calebl

YNAB MCP Server

by calebl
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Spending By Category

ynab_spending_by_category
Read-only

Totals spending per category over a date range, biggest spend first. Splits are counted through their subtransactions, and transfers between your own accounts are excluded.

Instructions

Totals spending per category over a date range, biggest spend first. Splits are counted through their subtransactions, and transfers between your own accounts are excluded. Totals are gross outflows: refunds and other inflows aren't netted, so they can differ from a category's activity in YNAB. With monthly: true, each category also gets a month-by-month series, its mean over full months, and how its last full month compares with the earlier ones.

Input Schema

NameRequiredDescriptionDefault
limitNoOnly return the top N categories by spend
monthsNoWith monthly: true, how many calendar months to cover, ending with the month of untilDate or the current month (default 6). sinceDate overrides it. Ignored without monthly.
planIdNoThe plan ID (optional, defaults to YNAB_PLAN_ID; budgetId is a deprecated alias)
monthlyNotrue adds the top-level months list and, on each category, monthly_totals (spend per month, aligned with months), average_monthly (mean over the full months) and change_pct (the last full month against the mean of the earlier full months). Months only partly in the range, or not over yet, are listed but left out of both figures. The range starts at sinceDate when given; otherwise it covers the number of calendar months set by months (default 6, at most 24), ending with untilDate or today. With many categories, pair it with limit.
budgetIdNoDeprecated alias of planId (still accepted)
sinceDateNoStart of the range, inclusive (ISO format: 2024-01-01). Defaults to 30 days ago.
untilDateNoEnd of the range, inclusive (ISO format: 2024-01-31). Defaults to no end date, or to today with monthly: true.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv0.6.0
    • addedInput schema / properties / monthly
      Added value: +{
+  "anyOf": [
+    {
+      "description": "true adds the top-level months list and, on each category, monthly_totals (spend per month, aligned with months), average_monthly (mean over the full months) and change_pct (the last full month against the mean of the earlier full months). Months only partly in the range, or not over yet, are listed but left out of both figures. The range starts at sinceDate when given; otherwise it covers the number of calendar months set by months (default 6, at most 24), ending with untilDate or today. With many categories, pair it with limit.",
+      "type": "boolean"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "true adds the top-level months list and, on each category, monthly_totals (spend per month, aligned with months), average_monthly (mean over the full months) and change_pct (the last full month against the mean of the earlier full months). Months only partly in the range, or not over yet, are listed but left out of both figures. The range starts at sinceDate when given; otherwise it covers the number of calendar months set by months (default 6, at most 24), ending with untilDate or today. With many categories, pair it with limit."
+}
    • addedInput schema / properties / months
      Added value: +{
+  "anyOf": [
+    {
+      "description": "With monthly: true, how many calendar months to cover, ending with the month of untilDate or the current month (default 6). sinceDate overrides it. Ignored without monthly.",
+      "maximum": 24,
+      "minimum": 1,
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "With monthly: true, how many calendar months to cover, ending with the month of untilDate or the current month (default 6). sinceDate overrides it. Ignored without monthly."
+}
    • changedInput schema / properties / untilDate / anyOf
      Previous value: -[
-  {
-    "description": "End of the range, inclusive (ISO format: 2024-01-31). Defaults to no end date.",
-    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "description": "End of the range, inclusive (ISO format: 2024-01-31). Defaults to no end date, or to today with monthly: true.",
+    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]
    • changedInput schema / properties / untilDate / description
      Previous value: -"End of the range, inclusive (ISO format: 2024-01-31). Defaults to no end date."New value: +"End of the range, inclusive (ISO format: 2024-01-31). Defaults to no end date, or to today with monthly: true."
  2. Addedv0.3.0

TDQS

A3.9/5.0
Behavior5/5

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

Goes well past the readOnly/destructive annotations: it discloses that splits are rolled through subtransactions, that own-account transfers are excluded, and that totals are gross outflows where refunds are not netted — an accounting caveat that will change how an agent interprets the numbers. It also flags that partial and in-progress months are listed but excluded from averages and change_pct.

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?

Four sentences, front-loaded with the core operation before the accounting caveats and the optional monthly mode. Slightly dense — the last sentence restates material already in the months/monthly schema descriptions — but no sentence 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?

With no output schema, the description usefully names the return concepts (per-category totals, monthly_totals, average_monthly, change_pct) and the exclusion rules that govern them. It stops short of describing the top-level response envelope or how categories with zero spend are represented, which an analytics tool of this shape could reasonably state.

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 description coverage is 100% and the schema's own monthly/sinceDate/untilDate descriptions are actually more detailed than the prose here, so the description adds little parameter meaning beyond a restatement of the monthly aggregation semantics. Baseline 3 is correct when the schema does the heavy lifting.

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 verb and resource (totals spending per category) plus the aggregation window and sort order ('biggest spend first'), which is far more than a restatement of the title. It never names the obvious alternative, ynab_spending_by_payee, so the category-vs-payee split must be inferred from the name rather than stated.

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?

Usage is implied rather than stated: the description covers defaults, the limit pairing hint ('With many categories, pair it with limit'), and how months/sinceDate interact, but never says when to pick this tool over ynab_spending_by_payee, ynab_cash_flow, or ynab_budget_summary. An agent must infer the selection from the resource noun.

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