ynab-mcpb

Overview Schema Source Related Servers Discussions Admin

ynab_list_transactions

Read-onlyIdempotent

Fetch YNAB transactions with filters for account, category, date, payee, amount, and cleared status, plus pagination to locate specific records or review budget activity.

Instructions

List transactions for a budget with optional filtering and pagination.

Args:

budget_id (string, optional): Budget UUID. Omit to use the default budget.
account_id (string, optional): Filter by account.
category_id (string, optional): Filter by category.
since_date (string, optional): ISO date (YYYY-MM-DD) to filter transactions on or after.
until_date (string, optional): ISO date (YYYY-MM-DD) to filter transactions on or before. Combine with since_date for a date window.
type (string, optional): "uncategorized" or "unapproved".
cleared (string, optional): "cleared", "uncleared", or "reconciled".
import_id (string, optional): Exact import_id, e.g. to find a transaction you just created.
payee_id (string, optional): Exact payee UUID.
payee_name (string, optional): Case-insensitive substring of the payee name.
amount_decimal (number, optional): Exact amount in currency units (e.g. -12.34). Or amount_milliunits for raw YNAB milliunits; pass at most one.
limit (int, optional): Max results per page. Default: 50.
offset (int, optional): Zero-based offset for pagination. Default: 0.
response_format (string, optional): "json" or "markdown" (default: "markdown").

Returns: transactions[], total_count, returned_count, offset, has_more, next_offset, cached, cache_info

Examples:

All transactions: call with no args (uses default budget)
Filter by account: set account_id
Last 30 days: set since_date to 30 days ago
Find a transaction: set account_id, since_date/until_date around its date, and payee_name or amount_decimal (or import_id)
Page 2: set limit=50, offset=50

Errors:

"No default budget set" → run ynab_set_default_budget first
Large result → use ynab_export_transactions to save to file

Input Schema

Name	Required	Description	Default
`type`	No
`limit`	No
`offset`	No
`cleared`	No
`payee_id`	No	Only this payee.
`budget_id`	No
`import_id`	No	Only the transaction with this exact import_id.
`account_id`	No
`payee_name`	No	Only payees whose name contains this text (case-insensitive).
`since_date`	No
`until_date`	No	Only transactions on or before this date (YYYY-MM-DD).
`category_id`	No
`amount_decimal`	No	Only transactions with exactly this amount in currency units (e.g. -12.34). Matches each row's amount: the parent amount, or the split-line amount when category_id is set (that path returns split lines).
`response_format`	No		markdown
`amount_milliunits`	No	Like amount_decimal, in raw YNAB milliunits.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed8 schema fields changedv0.32.0Nov 7, 2026

addedInput schema / properties / amount_decimal

Added value: +{
+  "description": "Only transactions with exactly this amount in currency units (e.g. -12.34). Matches each row's amount: the parent amount, or the split-line amount when category_id is set (that path returns split lines).",
+  "type": "number"
+}

addedInput schema / properties / amount_milliunits

Added value: +{
+  "description": "Like amount_decimal, in raw YNAB milliunits.",
+  "maximum": 9007199254740991,
+  "minimum": -9007199254740991,
+  "type": "integer"
+}

addedInput schema / properties / import_id

Added value: +{
+  "description": "Only the transaction with this exact import_id.",
+  "minLength": 1,
+  "type": "string"
+}

addedInput schema / properties / payee_id

Added value: +{
+  "description": "Only this payee.",
+  "minLength": 1,
+  "type": "string"
+}

addedInput schema / properties / payee_name

Added value: +{
+  "description": "Only payees whose name contains this text (case-insensitive).",
+  "minLength": 1,
+  "type": "string"
+}

addedInput schema / properties / since_date / format
```
Added value: +"date"
```
removedInput schema / properties / since_date / pattern
```
Removed value: -"^\\d{4}-\\d{2}-\\d{2}$"
```

addedInput schema / properties / until_date

Added value: +{
+  "description": "Only transactions on or before this date (YYYY-MM-DD).",
+  "format": "date",
+  "type": "string"
+}

Changed1 schema field changedv0.31.0Oct 29, 2026

changedOutput schema / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "cache_info": {
-        "description": "Human-readable cache status message (e.g., \"Cache hit\", \"Cache miss\")",
-        "type": "string"
-      },
-      "cached": {
-        "description": "Indicates if data was served from cache",
-        "type": "boolean"
-      },
-      "has_more": {
-        "description": "Whether more items exist beyond this page",
-        "type": "boolean"
-      },
-      "next_offset": {
-        "description": "Offset for next page, if has_more is true",
-        "maximum": 9007199254740991,
-        "minimum": -9007199254740991,
-        "type": "integer"
-      },
-      "offset": {
-        "description": "Offset used for this response",
-        "maximum": 9007199254740991,
-        "minimum": -9007199254740991,
-        "type": "integer"
-      },
-      "returned_count": {
-        "description": "Number of items returned",
-        "maximum": 9007199254740991,
-        "minimum": -9007199254740991,
-        "type": "integer"
-      },
-      "total_count": {
-        "description": "Total number of items available",
-        "maximum": 9007199254740991,
-        "minimum": -9007199254740991,
-        "type": "integer"
-      },
-      "transactions": {
-        "description": "List of transactions",
-        "items": {
-          "additionalProperties": false,
-          "properties": {
-            "account_id": {
-              "description": "Account ID",
-              "type": "string"
-            },
-            "account_name": {
-              "description": "Account name",
-              "type": "string"
-            },
-            "amount": {
-              "description": "Transaction amount in dollars",
-              "type": "number"
-            },
-            "approved": {
-              "description": "Approved flag",
-              "type": "boolean"
-            },
-            "category_id": {
-              "description": "Category ID",
-              "type": [
-                "string",
-                "null"
-              ]
-            },
-            "category_name": {
-              "description": "Category name",
-              "type": "string"
-            },
-            "cleared": {
-              "description": "Cleared status",
-              "type": "string"
-            },
-            "date": {
-              "description": "Transaction date",
-              "type": "string"
-            },
-            "deleted": {
-              "description": "Deleted flag",
-              "type": "boolean"
-            },
-            "flag_color": {
-              "description": "Flag color",
-              "type": "string"
-            },
-            "id": {
-              "description": "Transaction ID",
-              "type": "string"
-            },
-            "import_id": {
-              "description": "Import ID",
-              "type": "string"
-            },
-            "matched_transaction_id": {
-              "description": "Matched transaction ID",
-              "type": [
-                "string",
-                "null"
-              ]
-            },
-            "memo": {
-              "description": "Transaction memo",
-              "type": "string"
-            },
-            "payee_id": {
-              "description": "Payee ID",
-              "type": [
-                "string",
-                "null"
-              ]
-            },
-            "payee_name": {
-              "description": "Payee name",
-              "type": "string"
-            },
-            "transfer_account_id": {
-              "description": "Transfer account ID",
-              "type": [
-                "string",
-                "null"
-              ]
-            },
-            "transfer_transaction_id": {
-              "description": "Transfer transaction ID",
-              "type": [
-                "string",
-                "null"
-              ]
-            }
-          },
-          "required": [
-            "id",
-            "date",
-            "amount",
-            "cleared",
-            "approved",
-            "account_id",
-            "deleted"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      },
-      "usedDelta": {
-        "description": "Indicates if delta merge optimization was applied for budgets",
-        "type": "boolean"
-      }
-    },
-    "required": [
-      "total_count",
-      "returned_count",
-      "offset",
-      "has_more",
-      "transactions"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "estimated_size_kb": {
-        "description": "Estimated response size in KB",
-        "type": "number"
-      },
-      "message": {
-        "description": "Large result set message",
-        "type": "string"
-      },
-      "preview_transactions": {
-        "description": "Preview transactions",
-        "items": {
-          "additionalProperties": false,
-          "properties": {
-            "account_id": {
-              "description": "Account ID",
-              "type": "string"
-            },
-            "amount": {
-              "description": "Transaction amount in dollars",
-              "type": "number"
-            },
-            "category_name": {
-              "description": "Category name",
-              "type": "string"
-            },
-            "date": {
-              "description": "Transaction date",
-              "type": "string"
-            },
-            "id": {
-              "description": "Transaction ID",
-              "type": "string"
-            },
-            "memo": {
-              "description": "Transaction memo",
-              "type": "string"
-            },
-            "payee_name": {
-              "description": "Payee name",
-              "type": "string"
-            }
-          },
-          "required": [
-            "id",
-            "date",
-            "amount",
-            "account_id"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      },
-      "showing": {
-        "description": "Human-readable summary of transactions shown",
-        "type": "string"
-      },
-      "suggestion": {
-        "description": "Suggestion to narrow results",
-        "type": "string"
-      },
-      "total_count": {
-        "description": "Total transaction count",
-        "maximum": 9007199254740991,
-        "minimum": -9007199254740991,
-        "type": "integer"
-      }
-    },
-    "required": [
-      "message",
-      "suggestion",
-      "showing",
-      "total_count",
-      "estimated_size_kb",
-      "preview_transactions"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "cache_info": {
+        "description": "Human-readable cache status message (e.g., \"Cache hit\", \"Cache miss\")",
+        "type": "string"
+      },
+      "cached": {
+        "description": "Indicates if data was served from cache",
+        "type": "boolean"
+      },
+      "has_more": {
+        "description": "Whether more items exist beyond this page",
+        "type": "boolean"
+      },
+      "next_offset": {
+        "description": "Offset for next page, if has_more is true",
+        "maximum": 9007199254740991,
+        "minimum": -9007199254740991,
+        "type": "integer"
+      },
+      "offset": {
+        "description": "Offset used for this response",
+        "maximum": 9007199254740991,
+        "minimum": -9007199254740991,
+        "type": "integer"
+      },
+      "returned_count": {
+        "description": "Number of items returned",
+        "maximum": 9007199254740991,
+        "minimum": -9007199254740991,
+        "type": "integer"
+      },
+      "total_count": {
+        "description": "Total number of items available",
+        "maximum": 9007199254740991,
+        "minimum": -9007199254740991,
+        "type": "integer"
+      },
+      "transactions": {
+        "description": "List of transactions",
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "account_id": {
+              "type": "string"
+            },
+            "account_name": {
+              "type": "string"
+            },
+            "amount": {
+              "description": "Amount in decimal currency units",
+              "type": "number"
+            },
+            "amount_currency": {
+              "type": "number"
+            },
+            "amount_formatted": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "amount_milliunits": {
+              "maximum": 9007199254740991,
+              "minimum": -9007199254740991,
+              "type": "integer"
+            },
+            "approved": {
+              "type": "boolean"
+            },
+            "category_id": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "category_name": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "cleared": {
+              "type": "string"
+            },
+            "date": {
+              "type": "string"
+            },
+            "debt_transaction_type": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "deleted": {
+              "type": "boolean"
+            },
+            "flag_color": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "flag_name": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "id": {
+              "type": "string"
+            },
+            "import_id": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "import_payee_name": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "import_payee_name_original": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "matched_transaction_id": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "memo": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "parent_transaction_id": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "payee_id": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "payee_name": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "scheduled_transaction_id": {
+              "type": "string"
+            },
+            "subtransactions": {
+              "items": {
+                "additionalProperties": false,
+                "properties": {
+                  "amount": {
+                    "description": "Amount in decimal currency units",
+                    "type": "number"
+                  },
+                  "amount_currency": {
+                    "type": "number"
+                  },
+                  "amount_formatted": {
+                    "type": [
+                      "string",
+                      "null"
+                    ]
+                  },
+                  "amount_milliunits": {
+                    "maximum": 9007199254740991,
+                    "minimum": -9007199254740991,
+                    "type": "integer"
+                  },
+                  "category_id": {
+                    "type": [
+                      "string",
+                      "null"
+                    ]
+                  },
+                  "category_name": {
+                    "type": [
+                      "string",
+                      "null"
+                    ]
+                  },
+                  "deleted": {
+                    "type": "boolean"
+                  },
+                  "id": {
+                    "type": "string"
+                  },
+                  "memo": {
+                    "type": [
+                      "string",
+                      "null"
+                    ]
+                  },
+                  "payee_id": {
+                    "type": [
+                      "string",
+                      "null"
+                    ]
+                  },
+                  "payee_name": {
+                    "type": [
+                      "string",
+                      "null"
+                    ]
+                  },
+                  "scheduled_transaction_id": {
+                    "type": "string"
+                  },
+                  "transaction_id": {
+                    "type": "string"
+                  },
+                  "transfer_account_id": {
+                    "type": [
+                      "string",
+                      "null"
+                    ]
+                  },
+                  "transfer_transaction_id": {
+                    "type": [
+                      "string",
+                      "null"
+                    ]
+                  }
+                },
+                "required": [
+                  "amount"
+                ],
+                "type": "object"
+              },
+              "type": "array"
+            },
+            "transaction_id": {
+              "type": "string"
+            },
+            "transfer_account_id": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "transfer_transaction_id": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "type": {
+              "enum": [
+                "transaction",
+                "subtransaction"
+              ],
+              "type": "string"
+            }
+          },
+          "required": [
+            "id",
+            "amount",
+            "deleted",
+            "date",
+            "account_id",
+            "cleared",
+            "approved"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "usedDelta": {
+        "description": "Indicates if delta merge optimization was applied for budgets",
+        "type": "boolean"
+      }
+    },
+    "required": [
+      "total_count",
+      "returned_count",
+      "offset",
+      "has_more",
+      "transactions"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "estimated_size_kb": {
+        "description": "Estimated response size in KB",
+        "type": "number"
+      },
+      "message": {
+        "description": "Large result set message",
+        "type": "string"
+      },
+      "preview_transactions": {
+        "description": "Preview transactions",
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "account_id": {
+              "type": "string"
+            },
+            "account_name": {
+              "type": "string"
+            },
+            "amount": {
+              "description": "Amount in decimal currency units",
+              "type": "number"
+            },
+            "amount_currency": {
+              "type": "number"
+            },
+            "amount_formatted": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "amount_milliunits": {
+              "maximum": 9007199254740991,
+              "minimum": -9007199254740991,
+              "type": "integer"
+            },
+            "approved": {
+              "type": "boolean"
+            },
+            "category_id": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "category_name": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "cleared": {
+              "type": "string"
+            },
+            "date": {
+              "type": "string"
+            },
+            "debt_transaction_type": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "deleted": {
+              "type": "boolean"
+            },
+            "flag_color": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "flag_name": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "id": {
+              "type": "string"
+            },
+            "import_id": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "import_payee_name": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "import_payee_name_original": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "matched_transaction_id": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "memo": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "parent_transaction_id": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "payee_id": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "payee_name": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "scheduled_transaction_id": {
+              "type": "string"
+            },
+            "subtransactions": {
+              "items": {
+                "additionalProperties": false,
+                "properties": {
+                  "amount": {
+                    "description": "Amount in decimal currency units",
+                    "type": "number"
+                  },
+                  "amount_currency": {
+                    "type": "number"
+                  },
+                  "amount_formatted": {
+                    "type": [
+                      "string",
+                      "null"
+                    ]
+                  },
+                  "amount_milliunits": {
+                    "maximum": 9007199254740991,
+                    "minimum": -9007199254740991,
+                    "type": "integer"
+                  },
+                  "category_id": {
+                    "type": [
+                      "string",
+                      "null"
+                    ]
+                  },
+                  "category_name": {
+                    "type": [
+                      "string",
+                      "null"
+                    ]
+                  },
+                  "deleted": {
+                    "type": "boolean"
+                  },
+                  "id": {
+                    "type": "string"
+                  },
+                  "memo": {
+                    "type": [
+                      "string",
+                      "null"
+                    ]
+                  },
+                  "payee_id": {
+                    "type": [
+                      "string",
+                      "null"
+                    ]
+                  },
+                  "payee_name": {
+                    "type": [
+                      "string",
+                      "null"
+                    ]
+                  },
+                  "scheduled_transaction_id": {
+                    "type": "string"
+                  },
+                  "transaction_id": {
+                    "type": "string"
+                  },
+                  "transfer_account_id": {
+                    "type": [
+                      "string",
+                      "null"
+                    ]
+                  },
+                  "transfer_transaction_id": {
+                    "type": [
+                      "string",
+                      "null"
+                    ]
+                  }
+                },
+                "required": [
+                  "amount"
+                ],
+                "type": "object"
+              },
+              "type": "array"
+            },
+            "transaction_id": {
+              "type": "string"
+            },
+            "transfer_account_id": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "transfer_transaction_id": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "type": {
+              "enum": [
+                "transaction",
+                "subtransaction"
+              ],
+              "type": "string"
+            }
+          },
+          "required": [
+            "id",
+            "amount",
+            "date",
+            "account_id"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "showing": {
+        "description": "Human-readable summary of transactions shown",
+        "type": "string"
+      },
+      "suggestion": {
+        "description": "Suggestion to narrow results",
+        "type": "string"
+      },
+      "total_count": {
+        "description": "Total transaction count",
+        "maximum": 9007199254740991,
+        "minimum": -9007199254740991,
+        "type": "integer"
+      }
+    },
+    "required": [
+      "message",
+      "suggestion",
+      "showing",
+      "total_count",
+      "estimated_size_kb",
+      "preview_transactions"
+    ],
+    "type": "object"
+  }
+]

Changed1 schema field changedv0.29.1Oct 26, 2026

changedOutput schema / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "cache_info": {
-        "description": "Human-readable cache status message (e.g., \"Cache hit\", \"Cache miss\")",
-        "type": "string"
-      },
-      "cached": {
-        "description": "Indicates if data was served from cache",
-        "type": "boolean"
-      },
-      "has_more": {
-        "description": "Whether more items exist beyond this page",
-        "type": "boolean"
-      },
-      "next_offset": {
-        "description": "Offset for next page, if has_more is true",
-        "maximum": 9007199254740991,
-        "minimum": -9007199254740991,
-        "type": "integer"
-      },
-      "offset": {
-        "description": "Offset used for this response",
-        "maximum": 9007199254740991,
-        "minimum": -9007199254740991,
-        "type": "integer"
-      },
-      "returned_count": {
-        "description": "Number of items returned",
-        "maximum": 9007199254740991,
-        "minimum": -9007199254740991,
-        "type": "integer"
-      },
-      "total_count": {
-        "description": "Total number of items available",
-        "maximum": 9007199254740991,
-        "minimum": -9007199254740991,
-        "type": "integer"
-      },
-      "transactions": {
-        "description": "List of transactions",
-        "items": {
-          "additionalProperties": false,
-          "properties": {
-            "account_id": {
-              "description": "Account ID",
-              "type": "string"
-            },
-            "account_name": {
-              "description": "Account name",
-              "type": "string"
-            },
-            "amount": {
-              "description": "Transaction amount in dollars",
-              "type": "number"
-            },
-            "approved": {
-              "description": "Approved flag",
-              "type": "boolean"
-            },
-            "category_id": {
-              "anyOf": [
-                {
-                  "type": "string"
-                },
-                {
-                  "type": "null"
-                }
-              ],
-              "description": "Category ID"
-            },
-            "category_name": {
-              "description": "Category name",
-              "type": "string"
-            },
-            "cleared": {
-              "description": "Cleared status",
-              "type": "string"
-            },
-            "date": {
-              "description": "Transaction date",
-              "type": "string"
-            },
-            "deleted": {
-              "description": "Deleted flag",
-              "type": "boolean"
-            },
-            "flag_color": {
-              "description": "Flag color",
-              "type": "string"
-            },
-            "id": {
-              "description": "Transaction ID",
-              "type": "string"
-            },
-            "import_id": {
-              "description": "Import ID",
-              "type": "string"
-            },
-            "matched_transaction_id": {
-              "anyOf": [
-                {
-                  "type": "string"
-                },
-                {
-                  "type": "null"
-                }
-              ],
-              "description": "Matched transaction ID"
-            },
-            "memo": {
-              "description": "Transaction memo",
-              "type": "string"
-            },
-            "payee_id": {
-              "anyOf": [
-                {
-                  "type": "string"
-                },
-                {
-                  "type": "null"
-                }
-              ],
-              "description": "Payee ID"
-            },
-            "payee_name": {
-              "description": "Payee name",
-              "type": "string"
-            },
-            "transfer_account_id": {
-              "anyOf": [
-                {
-                  "type": "string"
-                },
-                {
-                  "type": "null"
-                }
-              ],
-              "description": "Transfer account ID"
-            },
-            "transfer_transaction_id": {
-              "anyOf": [
-                {
-                  "type": "string"
-                },
-                {
-                  "type": "null"
-                }
-              ],
-              "description": "Transfer transaction ID"
-            }
-          },
-          "required": [
-            "id",
-            "date",
-            "amount",
-            "cleared",
-            "approved",
-            "account_id",
-            "deleted"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      },
-      "usedDelta": {
-        "description": "Indicates if delta merge optimization was applied for budgets",
-        "type": "boolean"
-      }
-    },
-    "required": [
-      "total_count",
-      "returned_count",
-      "offset",
-      "has_more",
-      "transactions"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "estimated_size_kb": {
-        "description": "Estimated response size in KB",
-        "type": "number"
-      },
-      "message": {
-        "description": "Large result set message",
-        "type": "string"
-      },
-      "preview_transactions": {
-        "description": "Preview transactions",
-        "items": {
-          "additionalProperties": false,
-          "properties": {
-            "account_id": {
-              "description": "Account ID",
-              "type": "string"
-            },
-            "amount": {
-              "description": "Transaction amount in dollars",
-              "type": "number"
-            },
-            "category_name": {
-              "description": "Category name",
-              "type": "string"
-            },
-            "date": {
-              "description": "Transaction date",
-              "type": "string"
-            },
-            "id": {
-              "description": "Transaction ID",
-              "type": "string"
-            },
-            "memo": {
-              "description": "Transaction memo",
-              "type": "string"
-            },
-            "payee_name": {
-              "description": "Payee name",
-              "type": "string"
-            }
-          },
-          "required": [
-            "id",
-            "date",
-            "amount",
-            "account_id"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      },
-      "showing": {
-        "description": "Human-readable summary of transactions shown",
-        "type": "string"
-      },
-      "suggestion": {
-        "description": "Suggestion to narrow results",
-        "type": "string"
-      },
-      "total_count": {
-        "description": "Total transaction count",
-        "maximum": 9007199254740991,
-        "minimum": -9007199254740991,
-        "type": "integer"
-      }
-    },
-    "required": [
-      "message",
-      "suggestion",
-      "showing",
-      "total_count",
-      "estimated_size_kb",
-      "preview_transactions"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "cache_info": {
+        "description": "Human-readable cache status message (e.g., \"Cache hit\", \"Cache miss\")",
+        "type": "string"
+      },
+      "cached": {
+        "description": "Indicates if data was served from cache",
+        "type": "boolean"
+      },
+      "has_more": {
+        "description": "Whether more items exist beyond this page",
+        "type": "boolean"
+      },
+      "next_offset": {
+        "description": "Offset for next page, if has_more is true",
+        "maximum": 9007199254740991,
+        "minimum": -9007199254740991,
+        "type": "integer"
+      },
+      "offset": {
+        "description": "Offset used for this response",
+        "maximum": 9007199254740991,
+        "minimum": -9007199254740991,
+        "type": "integer"
+      },
+      "returned_count": {
+        "description": "Number of items returned",
+        "maximum": 9007199254740991,
+        "minimum": -9007199254740991,
+        "type": "integer"
+      },
+      "total_count": {
+        "description": "Total number of items available",
+        "maximum": 9007199254740991,
+        "minimum": -9007199254740991,
+        "type": "integer"
+      },
+      "transactions": {
+        "description": "List of transactions",
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "account_id": {
+              "description": "Account ID",
+              "type": "string"
+            },
+            "account_name": {
+              "description": "Account name",
+              "type": "string"
+            },
+            "amount": {
+              "description": "Transaction amount in dollars",
+              "type": "number"
+            },
+            "approved": {
+              "description": "Approved flag",
+              "type": "boolean"
+            },
+            "category_id": {
+              "description": "Category ID",
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "category_name": {
+              "description": "Category name",
+              "type": "string"
+            },
+            "cleared": {
+              "description": "Cleared status",
+              "type": "string"
+            },
+            "date": {
+              "description": "Transaction date",
+              "type": "string"
+            },
+            "deleted": {
+              "description": "Deleted flag",
+              "type": "boolean"
+            },
+            "flag_color": {
+              "description": "Flag color",
+              "type": "string"
+            },
+            "id": {
+              "description": "Transaction ID",
+              "type": "string"
+            },
+            "import_id": {
+              "description": "Import ID",
+              "type": "string"
+            },
+            "matched_transaction_id": {
+              "description": "Matched transaction ID",
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "memo": {
+              "description": "Transaction memo",
+              "type": "string"
+            },
+            "payee_id": {
+              "description": "Payee ID",
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "payee_name": {
+              "description": "Payee name",
+              "type": "string"
+            },
+            "transfer_account_id": {
+              "description": "Transfer account ID",
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "transfer_transaction_id": {
+              "description": "Transfer transaction ID",
+              "type": [
+                "string",
+                "null"
+              ]
+            }
+          },
+          "required": [
+            "id",
+            "date",
+            "amount",
+            "cleared",
+            "approved",
+            "account_id",
+            "deleted"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "usedDelta": {
+        "description": "Indicates if delta merge optimization was applied for budgets",
+        "type": "boolean"
+      }
+    },
+    "required": [
+      "total_count",
+      "returned_count",
+      "offset",
+      "has_more",
+      "transactions"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "estimated_size_kb": {
+        "description": "Estimated response size in KB",
+        "type": "number"
+      },
+      "message": {
+        "description": "Large result set message",
+        "type": "string"
+      },
+      "preview_transactions": {
+        "description": "Preview transactions",
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "account_id": {
+              "description": "Account ID",
+              "type": "string"
+            },
+            "amount": {
+              "description": "Transaction amount in dollars",
+              "type": "number"
+            },
+            "category_name": {
+              "description": "Category name",
+              "type": "string"
+            },
+            "date": {
+              "description": "Transaction date",
+              "type": "string"
+            },
+            "id": {
+              "description": "Transaction ID",
+              "type": "string"
+            },
+            "memo": {
+              "description": "Transaction memo",
+              "type": "string"
+            },
+            "payee_name": {
+              "description": "Payee name",
+              "type": "string"
+            }
+          },
+          "required": [
+            "id",
+            "date",
+            "amount",
+            "account_id"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "showing": {
+        "description": "Human-readable summary of transactions shown",
+        "type": "string"
+      },
+      "suggestion": {
+        "description": "Suggestion to narrow results",
+        "type": "string"
+      },
+      "total_count": {
+        "description": "Total transaction count",
+        "maximum": 9007199254740991,
+        "minimum": -9007199254740991,
+        "type": "integer"
+      }
+    },
+    "required": [
+      "message",
+      "suggestion",
+      "showing",
+      "total_count",
+      "estimated_size_kb",
+      "preview_transactions"
+    ],
+    "type": "object"
+  }
+]

Addedv0.26.9May 11, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint, so safety is covered; the description adds genuinely non-schema behavior: the default-budget fallback when budget_id is omitted, the 'No default budget set' error and its remedy, and the large-result escape hatch to export. It also warns that amount_decimal matching hits split-line amounts when category_id is set, which is real behavioral nuance. Minor redundancy in listing return fields that an output schema already provides keeps it at 4.

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?

Front-loaded summary followed by clean Args/Returns/Examples/Errors sections, which is the right structure for a 15-parameter tool. Some sentences restate the schema's own descriptions and the Returns line duplicates the output schema, but the length is proportionate to the parameter surface.

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 wide, all-optional query tool this covers what an agent needs: the default-budget behavior, filtering combos, pagination, error recovery, and an alternative for large result sets. Gaps are small — cache behavior (the returns include cached/cache_info) and any rate-limit expectations are unmentioned, and the Returns list is somewhat redundant given the output schema.

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 coverage is only 40%, so the description must carry the load and largely does: it states budget_id defaults to the default budget, gives ISO format for the date bounds and how to combine them, explains payee_name as a case-insensitive substring vs exact payee_id, constrains type/cleared to their enums, and flags that amount_decimal and amount_milliunits are mutually exclusive ('pass at most one'). It also documents limit (default 50) and offset (zero-based) pagination semantics.

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 first sentence gives a specific verb and resource ('List transactions for a budget') plus the two modifiers that matter (filtering, pagination). The plural 'list' immediately distances it from ynab_get_transaction and ynab_compare_transactions, and the Errors section points at ynab_export_transactions for the bulk case.

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?

Five concrete call recipes (no args, account_id, last 30 days, find-one-transaction, page 2) plus two error-driven routes ('run ynab_set_default_budget first', 'use ynab_export_transactions to save to file') give clear usage context. There is no explicit when-not-to-use guidance — e.g. that a single known transaction should go to ynab_get_transaction — so it stops short of a 5.

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

Deploy Server