Skip to main content
Glama
LandonSchropp

ynab-mcp-server

by LandonSchropp
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

Spending By Payee

ynab_spending_by_payee
Read-only

Totals spending by payee (merchant) over a date range, ranks largest spend first, and can include monthly trends to show where money goes.

Instructions

Totals spending per payee over a date range, biggest spend first - where the money actually goes by merchant. 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 payee 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 payees 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 payee, 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 payees, 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. First observedv0.7.1

TDQS

A4/5.0
Behavior5/5

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

Goes well beyond the read-only annotations by disclosing key semantics: splits are counted through subtransactions, internal transfers are excluded, totals are gross outflows with refunds/inflows not netted, and monthly mode adds month-by-month figures with specific treatment of partial months. This is exactly the behavioral context an agent needs to interpret results correctly.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the purpose in the first sentence, then layers in the critical behavioral caveats and the monthly option. Every sentence earns its place; there is no filler or repetition of the schema beyond a concise monthly summary.

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 an aggregation read tool with no output schema, the description covers purpose, exclusions, gross-vs-net semantics, and monthly output behavior well. It still does not describe the base return shape (e.g., payee name and total fields) or pagination/limit behavior, which would fully complete the picture.

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%, so the schema already documents all 7 parameters in detail, including monthly, months, sinceDate, untilDate, limit, and planId/budgetId. The description only summarizes the monthly behavior and does not add parameter semantics beyond what the schema provides, so baseline 3 is appropriate.

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?

States a specific verb and resource ('Totals spending per payee') plus scope ('over a date range, biggest spend first') and the merchant-spend angle. It contrasts implicitly with category activity but does not name the sibling ynab_spending_by_category, so sibling differentiation is present but not explicit.

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 when this tool is useful (merchant/payee-level spending) and notes that totals can differ from a category's activity. However, it gives no explicit when-to-use/when-not-to-use guidance or direct routing to alternatives such as ynab_spending_by_category.

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