Skip to main content
Glama
Sign In
ynab-mcpb

ynab-mcpb

by dizzlkheinz
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

ynab_get_month

Read-onlyIdempotent

Retrieve full budget data for a specific month, including all category balances, to review income, budgeted amounts, and activity.

Instructions

Get full budget data for a specific month including all category balances.

Args:

  • budget_id (string, optional): Budget UUID. Omit to use the default budget.

  • month (string, required): Month in YYYY-MM-DD format (use first day, e.g. "2025-01-01").

  • response_format (string, optional): "json" or "markdown" (default: "markdown").

Returns: month (month, income, budgeted, activity, to_be_budgeted, age_of_money, categories[]), cached, cache_info

Examples:

  • Get January 2025: set month="2025-01-01"

Errors:

  • "No default budget set" → run ynab_set_default_budget first

Input Schema

NameRequiredDescriptionDefault
monthYes
budget_idNo
response_formatNomarkdown

Output Schema

NameRequiredDescriptionDefault
monthYesMonth details
cachedNoIndicates if data was served from cache
usedDeltaNoIndicates if delta merge optimization was applied for budgets
cache_infoNoHuman-readable cache status message (e.g., "Cache hit", "Cache miss")

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.29.1
    • removedOutput schema / properties / month / properties / age_of_money / anyOf
      Removed value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]
    • addedOutput schema / properties / month / properties / age_of_money / type
      Added value: +[
+  "number",
+  "null"
+]
  2. Addedv0.26.9

TDQS

A4.3/5.0
Behavior4/5

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds what annotations cannot: that results may be served from cache (`cached`, `cache_info` in the return) and a documented error string with its recovery step. It never says when the cache is bypassed or how stale data can be, which keeps it below a 5.

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 purpose sentence is front-loaded and the Args/Returns/Examples/Errors blocks are scannable, with no filler prose. Some structure is redundant with the schema (parameter names and types restated), costing a small amount of space without adding meaning.

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?

For a read-only month-fetch, the definition covers required format, budget selection, output format choice, return fields, and the one known error path. With an output schema present, the Returns line is a bonus rather than a gap, and nothing needed to invoke the tool correctly is missing.

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

Parameters5/5

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

Schema description coverage is 0%, so the description must carry all three parameters and it does: budget_id's optionality and default-budget behavior, month's exact YYYY-MM-DD convention plus the non-obvious 'use first day' rule and a concrete example, and response_format's two values and markdown default. The first-day convention is genuinely additive beyond the schema's regex pattern.

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 first sentence names a specific verb and resource ('Get full budget data for a specific month') and adds a scope detail ('including all category balances') that separates it from ynab_list_months and ynab_get_budget. It stops short of naming a sibling explicitly, so an agent must infer the boundary rather than read it.

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

Usage Guidelines4/5

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

It states the default-budget fallback ('Omit to use the default budget') and routes a specific failure to a remedy ('run ynab_set_default_budget first'), which is real when-to-use guidance. It gives no explicit when-not or alternative-tool comparison, so it lands at clear-context-without-exclusions.

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