ynab-mcpb

Overview Schema Source Related Servers Discussions Admin

ynab_create_transaction

Create a single YNAB transaction with account, date, amount, payee, category, memo, flags, and optional split lines. Preview the validated request before saving.

Instructions

Create a single transaction in YNAB.

Args:

budget_id (string, optional): Budget UUID. Omit to use the default budget.
account_id (string, required): Account UUID.
amount_decimal (number, preferred): Amount in decimal currency units (for example, -50.00). Negative for expenses.
amount_milliunits (int, alternative): Explicit raw YNAB milliunits (for example, -50000).
amount (int, deprecated): Backward-compatible alias for amount_milliunits. Values are never guessed by magnitude.
date (string, required): ISO date YYYY-MM-DD.
payee_name (string, optional): Payee name (creates new payee if not found).
payee_id (string, optional): Existing payee UUID (alternative to payee_name).
category_id (string, optional): Category UUID.
memo (string, optional): Memo text.
cleared (string, optional): "cleared", "uncleared", or "reconciled". Default: "uncleared".
approved (boolean, optional): Mark as approved. Default: false.
flag_color (string, optional): Transaction flag color ("red", "orange", "yellow", "green", "blue", "purple").
dry_run (boolean, optional): Preview without saving. Default: false.
subtransactions (array, optional): Manual split lines. Each entry uses exactly one of amount_decimal, amount_milliunits, or deprecated amount, plus optional "memo", "category_id", "payee_id", and "payee_name".

Use "subtransactions" for manual split transactions. Use "ynab_create_receipt_split_transaction" when you have itemized receipt data and want proportional tax allocation handled for you. Advanced: "import_id" is supported, but it is intentionally not part of normal guidance. Usually omit it if you want the transaction to remain eligible for later bank-import matching.

Returns: the created transaction, including split lines and explicit amount_milliunits.

Examples:

$50 expense: set amount_decimal=-50.00
Already-converted data: set amount_milliunits=-50000

Write safety: call without confirmation_token to preview. The preview returns confirmation_token and confirmation_expires_at in its structured output (and in its text). Execute the identical validated request with that short-lived confirmation_token.

Input Schema

Name	Required	Description
`date`	Yes
`memo`	No
`amount`	No	Deprecated legacy alias for amount_milliunits. Use amount_decimal for currency input or amount_milliunits for raw YNAB values.
`cleared`	No
`dry_run`	No
`approved`	No
`payee_id`	No
`budget_id`	No
`import_id`	No
`account_id`	Yes
`flag_color`	No
`payee_name`	No
`category_id`	No
`amount_decimal`	No	Preferred: amount in decimal currency units (for example, -12.34). Rounded exactly to the nearest YNAB milliunit.
`subtransactions`	No
`amount_milliunits`	No	Raw YNAB milliunits. Use only when the value is already converted.
`confirmation_token`	No	Short-lived, single-use token returned by the immediately preceding preview of this exact validated request. Omit, or pass null or an empty string, to preview.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.32.0Nov 7, 2026

changedOutput schema / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "action": {
-        "const": "ynab_create_transaction",
-        "type": "string"
-      },
-      "dry_run": {
-        "const": true,
-        "type": "boolean"
-      },
-      "request": {
-        "additionalProperties": {},
-        "propertyNames": {
-          "type": "string"
-        },
-        "type": "object"
-      }
-    },
-    "required": [
-      "dry_run",
-      "action",
-      "request"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "transaction": {
-        "additionalProperties": false,
-        "properties": {
-          "account_balance": {
-            "type": "number"
-          },
-          "account_cleared_balance": {
-            "type": "number"
-          },
-          "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": [
-                "id",
-                "transaction_id",
-                "amount",
-                "deleted"
-              ],
-              "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"
-      }
-    },
-    "required": [
-      "transaction"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "action": {
+        "const": "ynab_create_transaction",
+        "type": "string"
+      },
+      "confirmation_expires_at": {
+        "description": "Preview only: when confirmation_token expires (ISO 8601).",
+        "format": "date-time",
+        "type": "string"
+      },
+      "confirmation_token": {
+        "description": "Preview only: single-use token that executes this exact request when passed back as confirmation_token.",
+        "type": "string"
+      },
+      "dry_run": {
+        "const": true,
+        "type": "boolean"
+      },
+      "request": {
+        "additionalProperties": {},
+        "propertyNames": {
+          "type": "string"
+        },
+        "type": "object"
+      },
+      "warnings": {
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "code": {
+              "type": "string"
+            },
+            "count": {
+              "type": "number"
+            },
+            "message": {
+              "type": "string"
+            },
+            "sample_ids": {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            }
+          },
+          "required": [
+            "code",
+            "count",
+            "message"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      }
+    },
+    "required": [
+      "dry_run",
+      "action",
+      "request"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "confirmation_expires_at": {
+        "description": "Preview only: when confirmation_token expires (ISO 8601).",
+        "format": "date-time",
+        "type": "string"
+      },
+      "confirmation_token": {
+        "description": "Preview only: single-use token that executes this exact request when passed back as confirmation_token.",
+        "type": "string"
+      },
+      "transaction": {
+        "additionalProperties": false,
+        "properties": {
+          "account_balance": {
+            "type": "number"
+          },
+          "account_cleared_balance": {
+            "type": "number"
+          },
+          "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": [
+                "id",
+                "transaction_id",
+                "amount",
+                "deleted"
+              ],
+              "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"
+      }
+    },
+    "required": [
+      "transaction"
+    ],
+    "type": "object"
+  }
+]

Changed5 schema fields changedv0.31.0Oct 29, 2026

addedInput schema / properties / confirmation_token / anyOf

Added value: +[
+  {
+    "minLength": 16,
+    "type": "string"
+  },
+  {
+    "const": ""
+  },
+  {
+    "type": "null"
+  }
+]

changedInput schema / properties / confirmation_token / description

Previous value: -"Short-lived, single-use token returned by the immediately preceding preview of this exact validated request."New value: +"Short-lived, single-use token returned by the immediately preceding preview of this exact validated request. Omit, or pass null or an empty string, to preview."

removedInput schema / properties / confirmation_token / minLength
```
Removed value: -16
```
removedInput schema / properties / confirmation_token / type
```
Removed value: -"string"
```

changedOutput schema / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "action": {
-        "const": "ynab_create_transaction",
-        "type": "string"
-      },
-      "dry_run": {
-        "const": true,
-        "type": "boolean"
-      },
-      "request": {
-        "additionalProperties": {},
-        "propertyNames": {
-          "type": "string"
-        },
-        "type": "object"
-      }
-    },
-    "required": [
-      "dry_run",
-      "action",
-      "request"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "transaction": {
-        "additionalProperties": false,
-        "properties": {
-          "account_balance": {
-            "type": "number"
-          },
-          "account_cleared_balance": {
-            "type": "number"
-          },
-          "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"
-          },
-          "subtransactions": {
-            "items": {
-              "additionalProperties": false,
-              "properties": {
-                "amount": {
-                  "type": "number"
-                },
-                "category_id": {
-                  "type": "string"
-                },
-                "category_name": {
-                  "type": "string"
-                },
-                "deleted": {
-                  "type": "boolean"
-                },
-                "id": {
-                  "type": "string"
-                },
-                "memo": {
-                  "type": "string"
-                },
-                "payee_id": {
-                  "type": "string"
-                },
-                "payee_name": {
-                  "type": "string"
-                },
-                "transaction_id": {
-                  "type": "string"
-                },
-                "transfer_account_id": {
-                  "type": "string"
-                },
-                "transfer_transaction_id": {
-                  "type": "string"
-                }
-              },
-              "required": [
-                "id",
-                "transaction_id",
-                "amount",
-                "deleted"
-              ],
-              "type": "object"
-            },
-            "type": "array"
-          },
-          "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"
-      }
-    },
-    "required": [
-      "transaction"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "action": {
+        "const": "ynab_create_transaction",
+        "type": "string"
+      },
+      "dry_run": {
+        "const": true,
+        "type": "boolean"
+      },
+      "request": {
+        "additionalProperties": {},
+        "propertyNames": {
+          "type": "string"
+        },
+        "type": "object"
+      }
+    },
+    "required": [
+      "dry_run",
+      "action",
+      "request"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "transaction": {
+        "additionalProperties": false,
+        "properties": {
+          "account_balance": {
+            "type": "number"
+          },
+          "account_cleared_balance": {
+            "type": "number"
+          },
+          "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": [
+                "id",
+                "transaction_id",
+                "amount",
+                "deleted"
+              ],
+              "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"
+      }
+    },
+    "required": [
+      "transaction"
+    ],
+    "type": "object"
+  }
+]

Changed1 schema field changedv0.29.1Oct 26, 2026

changedOutput schema / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "action": {
-        "const": "ynab_create_transaction",
-        "type": "string"
-      },
-      "dry_run": {
-        "const": true,
-        "type": "boolean"
-      },
-      "request": {
-        "additionalProperties": {},
-        "propertyNames": {
-          "type": "string"
-        },
-        "type": "object"
-      }
-    },
-    "required": [
-      "dry_run",
-      "action",
-      "request"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "transaction": {
-        "additionalProperties": false,
-        "properties": {
-          "account_balance": {
-            "type": "number"
-          },
-          "account_cleared_balance": {
-            "type": "number"
-          },
-          "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"
-          },
-          "subtransactions": {
-            "items": {
-              "additionalProperties": false,
-              "properties": {
-                "amount": {
-                  "type": "number"
-                },
-                "category_id": {
-                  "type": "string"
-                },
-                "category_name": {
-                  "type": "string"
-                },
-                "deleted": {
-                  "type": "boolean"
-                },
-                "id": {
-                  "type": "string"
-                },
-                "memo": {
-                  "type": "string"
-                },
-                "payee_id": {
-                  "type": "string"
-                },
-                "payee_name": {
-                  "type": "string"
-                },
-                "transaction_id": {
-                  "type": "string"
-                },
-                "transfer_account_id": {
-                  "type": "string"
-                },
-                "transfer_transaction_id": {
-                  "type": "string"
-                }
-              },
-              "required": [
-                "id",
-                "transaction_id",
-                "amount",
-                "deleted"
-              ],
-              "type": "object"
-            },
-            "type": "array"
-          },
-          "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"
-      }
-    },
-    "required": [
-      "transaction"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "action": {
+        "const": "ynab_create_transaction",
+        "type": "string"
+      },
+      "dry_run": {
+        "const": true,
+        "type": "boolean"
+      },
+      "request": {
+        "additionalProperties": {},
+        "propertyNames": {
+          "type": "string"
+        },
+        "type": "object"
+      }
+    },
+    "required": [
+      "dry_run",
+      "action",
+      "request"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "transaction": {
+        "additionalProperties": false,
+        "properties": {
+          "account_balance": {
+            "type": "number"
+          },
+          "account_cleared_balance": {
+            "type": "number"
+          },
+          "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"
+          },
+          "subtransactions": {
+            "items": {
+              "additionalProperties": false,
+              "properties": {
+                "amount": {
+                  "type": "number"
+                },
+                "category_id": {
+                  "type": "string"
+                },
+                "category_name": {
+                  "type": "string"
+                },
+                "deleted": {
+                  "type": "boolean"
+                },
+                "id": {
+                  "type": "string"
+                },
+                "memo": {
+                  "type": "string"
+                },
+                "payee_id": {
+                  "type": "string"
+                },
+                "payee_name": {
+                  "type": "string"
+                },
+                "transaction_id": {
+                  "type": "string"
+                },
+                "transfer_account_id": {
+                  "type": "string"
+                },
+                "transfer_transaction_id": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "id",
+                "transaction_id",
+                "amount",
+                "deleted"
+              ],
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "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"
+      }
+    },
+    "required": [
+      "transaction"
+    ],
+    "type": "object"
+  }
+]

Changed9 schema fields changedv0.27.1Jul 12, 2026

addedInput schema / properties / amount / description

Added value: +"Deprecated legacy alias for amount_milliunits. Use amount_decimal for currency input or amount_milliunits for raw YNAB values."

addedInput schema / properties / amount_decimal

Added value: +{
+  "description": "Preferred: amount in decimal currency units (for example, -12.34). Rounded exactly to the nearest YNAB milliunit.",
+  "type": "number"
+}

addedInput schema / properties / amount_milliunits

Added value: +{
+  "description": "Raw YNAB milliunits. Use only when the value is already converted.",
+  "maximum": 9007199254740991,
+  "minimum": -9007199254740991,
+  "type": "integer"
+}

addedInput schema / properties / confirmation_token

Added value: +{
+  "description": "Short-lived, single-use token returned by the immediately preceding preview of this exact validated request.",
+  "minLength": 16,
+  "type": "string"
+}

addedInput schema / properties / subtransactions / items / properties / amount / description
```
Added value: +"Deprecated legacy alias for amount_milliunits on this split line."
```

addedInput schema / properties / subtransactions / items / properties / amount_decimal

Added value: +{
+  "description": "Preferred: amount in decimal currency units (for example, -12.34). Rounded exactly to the nearest YNAB milliunit.",
+  "type": "number"
+}

addedInput schema / properties / subtransactions / items / properties / amount_milliunits

Added value: +{
+  "description": "Raw YNAB milliunits. Use only when the value is already converted.",
+  "maximum": 9007199254740991,
+  "minimum": -9007199254740991,
+  "type": "integer"
+}

removedInput schema / properties / subtransactions / items / required
```
Removed value: -[
-  "amount"
-]
```

changedInput schema / required

Previous value: -[
-  "account_id",
-  "amount",
-  "date"
-]New value: +[
+  "account_id",
+  "date"
+]

Addedv0.26.9May 11, 2026

TDQS

A4.7/5.0

Behavior4/5

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

Annotations only declare the safety profile (not read-only, not idempotent, open-world, non-destructive); the description adds materially more: the two-phase preview/confirm write gate, that payee_name creates a new payee if not found (a side effect beyond the transaction itself), the cleared/approved defaults, and that import_id is intentionally omitted so the transaction stays eligible for bank-import matching. It stops short of describing failure modes or which permission/scope is required.

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 lead sentence and the closing guidance about alternatives, import_id, and write safety are front-loaded and earn their place. The Aargs block partially echoes the schema's field list, but given the very low schema coverage it carries genuine disambiguating information rather than repetition; it is long but not padded.

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 17-parameter write tool with an output schema, the description covers the full picture: amount semantics, split handling, budget/account defaults, the preview-then-confirm flow, and sibling alternatives. Return values are correctly left to the output schema and only summarized briefly.

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 only 24% across 17 parameters, but the description compensates thoroughly: it labels amount_decimal as preferred, amount_milliunits as raw alternative, amount as deprecated, and explicitly notes 'Values are never guessed by magnitude' — resolving real ambiguity between the three overlapping amount fields. It also documents subtransaction composition ('exactly one of amount_decimal, amount_milliunits, or deprecated amount') and the payee_name vs payee_id alternative.

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?

Opens with 'Create a single transaction in YNAB' — a specific verb plus resource, with 'single' implicitly contrasting the plural sibling ynab_create_transactions. It also explicitly routes split cases to ynab_create_receipt_split_transaction, so an agent can distinguish it from both sibling creation tools.

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

Usage Guidelines5/5

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

Explicitly states when to prefer 'subtransactions' (manual splits) versus ynab_create_receipt_split_transaction (itemized receipts with proportional tax allocation). It also prescribes the exact invocation sequence — call without confirmation_token to preview, then re-execute with the returned short-lived token — which is the critical when/how guidance for this write tool.

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

Deploy Server

ynab_create_transaction

Instructions

Input Schema

Output Schema

Schema Changelog

TDQS

Other Tools