YNAB MCP Server

Review Unapproved

review_unapproved

Read-onlyIdempotent

Review unapproved YNAB transactions grouped by payee and approval readiness, with flags for splits, transfers, and category issues. Choose summary or compact modes for large queues.

Instructions

Unapproved transactions across all history, split into ready_to_approve (categorized, split, or transfer; grouped by payee) and needs_category_first. Each row carries flags: manually_entered, match_broken (cosmetic; the row is still editable), scheduled_transaction_realized (composite id, writable), new_payee, no_prior_amount_match, category_drift:was_X. Group headers report category_names and mixed_categories (category_name is null when mixed) and a net total with inflow_total/outflow_total when signs are mixed; see resource ynab://guide/flags-reference. Large queues: summary:true returns counts and per-payee aggregates; compact:true keeps ids and essentials only. Above maxTransactions rows (default 400) the response drops to compact, then summary, and reports mode.

Input Schema

TableJSON Schema

Name	Required	Description
`compact`	No	If true (and summary is not set), keep per-transaction rows but only the fields needed to act (id, date, payee_name, amount, category_name, account_name, flags; matched_transaction_id for match_broken rows).
`summary`	No	If true, omit per-transaction details from the response and return only counts + by-payee aggregates (for both ready_to_approve and needs_category_first). Use this when the full unapproved queue is large; drill into specifics with get_transactions afterwards.
`budgetId`	No	Budget ID (uses default if not provided)
`maxTransactions`	No	Above this many unapproved rows (default 400) a full response degrades to compact, and above twice it to summary; the response reports mode and a notice. Raise it to force detail.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv5.4.0Sep 15, 2026

changedInput schema / properties / compact / description

Previous value: -"If true (and summary is not set), keep per-transaction detail but return only the fields needed to act — id, date, payee_name, amount, category_name, account_name, flags — dropping bulky fields (import strings, subtransactions, import ids) that push the full response past the inline size limit. Rows flagged match_broken additionally keep matched_transaction_id, since triaging that flag means GETting the matched id. Use when you need transaction IDs to approve or recategorize but the full queue would overflow."New value: +"If true (and summary is not set), keep per-transaction rows but only the fields needed to act (id, date, payee_name, amount, category_name, account_name, flags; matched_transaction_id for match_broken rows)."

addedInput schema / properties / maxTransactions

Added value: +{
+  "description": "Above this many unapproved rows (default 400) a full response degrades to compact, and above twice it to summary; the response reports mode and a notice. Raise it to force detail.",
+  "maximum": 2000,
+  "minimum": 1,
+  "type": "integer"
+}

removedOutput schema / properties / result / description

Removed value: -"Structured result returned by Review Unapproved."

Changed1 schema field changedv5.2.0Aug 29, 2026

changedInput schema / properties / compact / description

Previous value: -"If true (and summary is not set), keep per-transaction detail but return only the fields needed to act — id, date, payee_name, amount, category_name, account_name, flags — dropping bulky fields (import strings, subtransactions, matched/import ids) that push the full response past the inline size limit. Use when you need transaction IDs to approve or recategorize but the full queue would overflow."New value: +"If true (and summary is not set), keep per-transaction detail but return only the fields needed to act — id, date, payee_name, amount, category_name, account_name, flags — dropping bulky fields (import strings, subtransactions, import ids) that push the full response past the inline size limit. Rows flagged match_broken additionally keep matched_transaction_id, since triaging that flag means GETting the matched id. Use when you need transaction IDs to approve or recategorize but the full queue would overflow."

Changed1 schema field changedv5.1.1Jul 21, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "result": {
+      "description": "Structured result returned by Review Unapproved."
+    }
+  },
+  "required": [
+    "result"
+  ],
+  "type": "object"
+}

Changed1 schema field changedv3.1.0Jul 5, 2026

addedInput schema / properties / compact

Added value: +{
+  "description": "If true (and summary is not set), keep per-transaction detail but return only the fields needed to act — id, date, payee_name, amount, category_name, account_name, flags — dropping bulky fields (import strings, subtransactions, matched/import ids) that push the full response past the inline size limit. Use when you need transaction IDs to approve or recategorize but the full queue would overflow.",
+  "type": "boolean"
+}

First observedv2.0.0May 28, 2026

TDQS

A4.8/5.0

Behavior5/5

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

The description adds substantial behavioral context beyond the readOnlyHint/idempotentHint annotations: it explains flag semantics (match_broken is cosmetic and row remains editable, scheduled_transaction_realized is writable), degradation behavior (compact/summary fallback above thresholds), and response grouping details. This enriches the agent's understanding without contradicting annotations.

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?

The description is dense but well-structured, front-loading the core purpose and then logically detailing flags, grouping, and degradation. Every sentence adds unique value, and the use of semicolons and clauses keeps it readable. It is appropriately sized for the complexity of the tool.

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?

Given the output schema exists (as indicated) and annotations cover safety, the description covers all necessary aspects: the categories, flags, grouping headers, degradation modes, and references to a flags reference. An agent can invoke the tool correctly and interpret the response without ambiguity.

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?

Despite 100% schema coverage, the description adds meaningful semantics: it explains the effect of summary:true and compact:true, the degradation logic tied to maxTransactions, and the default of 400. These behavioral details are not in the schema, significantly enhancing parameter understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Unapproved transactions across all history', split into ready_to_approve and needs_category_first. It specifies the resource (unapproved transactions) and the action (review), distinguishing it from sibling tools like get_transactions or search_transactions. The verb and scope are explicit and not a tautology.

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?

The description provides clear context for when to use the tool (reviewing unapproved transactions) and explains parameter usage for large queues (summary:true, compact:true, maxTransactions). However, it does not explicitly mention alternatives or when not to use it, leaving the selection among siblings to inference.

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