YNAB MCP Server

Search Transactions

search_transactions

Read-onlyIdempotent

Find YNAB transactions by case-insensitive text across payee, bank payee, memo, account, category, or split details, or by absolute dollar amount; apply account/date filters and paginate results.

Instructions

Search query and/or amount (one required). Case-insensitive substrings: payee, raw bank payee, memo, account, category, split payee/memo/category. Amount: absolute dollars within half a cent. Filters apply after fetching account/date-bounded history. Newest first; paginate with next_offset.

Input Schema

Name	Required	Description
`limit`	No	Page size (default 50, max 500)
`query`	No	Text to find in payee, raw import payee, memo, account, or category (case-insensitive substring)
`amount`	No	Amount in dollars to match on absolute value (12.34 matches -12.34 and 12.34)
`offset`	No	Number of matches to skip (default 0); pass next_offset from the previous page
`budgetId`	No
`accountId`	No	Restrict the search to one account
`freshness`	No	fresh (default) reads YNAB. cached uses a session-isolated 30-second cache; complete means its reported coverage, which expands for older requested dates. Reports freshness; caller delta cursors bypass retention.
`sinceDate`	No	From YYYY-MM-DD, inclusive; default one year ago.
`untilDate`	No	Through YYYY-MM-DD, inclusive
`projection`	No	Output fields: full (default) or lean IDs, values and essential status/link fields. Splits retain child IDs and amounts.
`includeFreshness`	No	Return an envelope with freshness/coverage metadata even on a fresh read.

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed8 schema fields changedv6.1.0Oct 25, 2026

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 / freshness

Added value: +{
+  "description": "fresh (default) reads YNAB. cached uses a session-isolated 30-second cache; complete means its reported coverage, which expands for older requested dates. Reports freshness; caller delta cursors bypass retention.",
+  "enum": [
+    "fresh",
+    "cached"
+  ],
+  "type": "string"
+}

addedInput schema / properties / includeFreshness

Added value: +{
+  "description": "Return an envelope with freshness/coverage metadata even on a fresh read.",
+  "type": "boolean"
+}

addedInput schema / properties / projection

Added value: +{
+  "description": "Output fields: full (default) or lean IDs, values and essential status/link fields. Splits retain child IDs and amounts.",
+  "enum": [
+    "lean",
+    "full"
+  ],
+  "type": "string"
+}

changedInput schema / properties / sinceDate / description

Previous value: -"Only search transactions on or after this date (YYYY-MM-DD). If omitted, YNAB defaults to one year ago."New value: +"From YYYY-MM-DD, inclusive; default one year ago."

changedInput schema / properties / untilDate / description

Previous value: -"Only search transactions on or before this date (YYYY-MM-DD)"New value: +"Through YYYY-MM-DD, inclusive"

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Addedv5.4.0Sep 15, 2026

TDQS

A3.8/5.0

Behavior4/5

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

Annotations already cover read-only, idempotent and non-destructive, so the description rightly spends its space on traits annotations cannot express: matching semantics, half-cent amount tolerance, newest-first ordering, and next_offset pagination. The note that filters are applied after the account/date-bounded fetch is a genuinely useful performance disclosure.

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?

Very tight and front-loaded — purpose first, then match semantics, then cost/pagination behavior. The telegraphic fragment style ("Amount: absolute dollars within half a cent.") is dense but every clause carries information; nothing is padding.

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 an output schema present and 91% schema coverage across 11 params, the description need not document returns or every field. It covers what the schema cannot: the required-one-of constraint, match scope including splits, and result ordering. Minor omission: it never says what happens if both query and amount are supplied (AND vs OR).

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 91% so the baseline is 3, and the description still adds real value: it states that one of query/amount is required (the schema marks nothing required), names split payee/memo/category as searchable fields that the query parameter description omits, and specifies the half-cent tolerance the amount param only implies.

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 (search transactions) and immediately narrows the matching model: case-insensitive substrings over payee, raw bank payee, memo, account, category, plus absolute-dollar amount matching. That is enough to distinguish it from list-style siblings like get_transactions, though it never names an alternative 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?

"one required" plus "Filters apply after fetching account/date-bounded history" implies the intended usage and hints that date/account bounds are the real cost driver. However, no sibling is named as the alternative (get_transactions, search_payees), and there is no explicit when-not-to-use guidance.

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

Deploy Server