Skip to main content
Glama
YNAB MCP Server

YNAB MCP Server

by rgarcia

Gettransactions

getTransactions

Retrieve plan transactions, excluding pending entries; filter by date range or type to limit results and avoid overflowing context with a full year of data.

Instructions

Returns plan transactions, excluding any pending transactions

IMPORTANT: this can return thousands of transactions and overflow your context. Always pass since_date (and until_date when you know it) covering only the dates you need, such as the last 7 to 30 days. Without since_date, YNAB returns a full year. Pass type="unapproved" or type="uncategorized" when you only need those transactions.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "plan_id": "<plan_id>"
    },
    "name": "getTransactions"
  }
}

Input Schema

NameRequiredDescriptionDefault
typeNoIf specified, only transactions of the specified type will be included. "uncategorized" and "unapproved" are currently supported.
plan_idYesThe id of the plan. "last-used" can be used to specify the last used plan and "default" can be used if default plan selection is enabled (see: https://api.ynab.com/#oauth-default-plan).
since_dateNoIf specified, only transactions on or after this date will be included. The date should be ISO formatted (e.g. 2016-12-30). Defaults to one year ago when not specified.
until_dateNoIf specified, only transactions on or before this date will be included. The date should be ISO formatted (e.g. 2016-12-30).
last_knowledge_of_serverNoThe starting server knowledge. If provided, only entities that have changed since `last_knowledge_of_server` will be included.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.2.0
    • changedInput schema / properties / since_date / description
      Previous value: -"If specified, only transactions on or after this date will be included.  The date should be ISO formatted (e.g. 2016-12-30)."New value: +"If specified, only transactions on or after this date will be included.  The date should be ISO formatted (e.g. 2016-12-30). Defaults to one year ago when not specified."
    • addedInput schema / properties / until_date
      Added value: +{
      +  "description": "If specified, only transactions on or before this date will be included.  The date should be ISO formatted (e.g. 2016-12-30).",
      +  "format": "date",
      +  "type": "string"
      +}
  2. First observedv0.1.0

TDQS

A4.3/5.0
Behavior5/5

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

With no annotations provided, the description carries the full burden and does so well: it warns the result can contain thousands of transactions and overflow context, and discloses the default behavior (a full year) when since_date is omitted. These are exactly the operational traits an agent needs before invoking a large read.

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?

Three sentences, front-loaded with the return scope and followed by an IMPORTANT callout for the highest-risk behavior. Every sentence contributes a distinct actionable constraint with no 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 five-parameter read with no annotations and no output schema, the description covers context-overflow risk, default date range, and filtering adequately. It does not mention the incremental-sync parameter (last_knowledge_of_server) or the shape of what comes back, leaving minor gaps.

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 baseline is 3; the description earns above that by elevating since_date/until_date from optional to effectively required with a recommended 7-30 day window and by explaining the practical intent of the type filter. It adds operational meaning rather than restating types.

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 opens with a specific verb and resource: "Returns plan transactions," and adds a scope qualifier (pending transactions excluded). It is clearly distinguishable from write siblings like updateTransactions, though it does not explicitly distinguish itself from getTransactionsByAccount or getTransactionsByMonth.

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 gives concrete when-to-use guidance for parameters: always pass since_date (and until_date when known) covering only the dates needed, and use type="unapproved" or type="uncategorized" when only those are wanted. It lacks explicit routing to sibling tools for account/category/month-scoped queries, which is the only gap.

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