ynab-mcpb

Overview Schema Source Related Servers Discussions Admin

ynab_create_account

Create a new account in a YNAB budget by specifying its name and type, with optional opening balance and dry-run preview before saving.

Instructions

Create a new account in a YNAB budget.

Args:

budget_id (string, optional): Budget UUID. Omit to use the default budget.
name (string, required): Account name.
type (string, required): One of: checking, savings, creditCard, cash, lineOfCredit, otherAsset, otherLiability.
balance (number, optional): Opening balance in dollars. Default: 0.
dry_run (boolean, optional): Preview the request without creating. Default: false.

Returns: account object with id, name, type, balance fields.

Examples:

Create checking account: set name="My Checking", type="checking"
Dry run: set dry_run=true to preview without saving

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
`name`	Yes
`type`	Yes
`balance`	No
`dry_run`	No
`budget_id`	No
`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_account",
-        "type": "string"
-      },
-      "dry_run": {
-        "const": true,
-        "type": "boolean"
-      },
-      "request": {
-        "additionalProperties": false,
-        "properties": {
-          "balance": {
-            "type": "number"
-          },
-          "budget_id": {
-            "type": "string"
-          },
-          "name": {
-            "type": "string"
-          },
-          "type": {
-            "type": "string"
-          }
-        },
-        "required": [
-          "budget_id",
-          "name",
-          "type",
-          "balance"
-        ],
-        "type": "object"
-      }
-    },
-    "required": [
-      "dry_run",
-      "action",
-      "request"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "account": {
-        "additionalProperties": false,
-        "properties": {
-          "balance": {
-            "description": "Account balance in dollars",
-            "type": "number"
-          },
-          "cleared_balance": {
-            "description": "Cleared balance in dollars",
-            "type": "number"
-          },
-          "closed": {
-            "description": "Closed flag",
-            "type": "boolean"
-          },
-          "direct_import_in_error": {
-            "description": "Direct import error flag",
-            "type": "boolean"
-          },
-          "direct_import_linked": {
-            "description": "Direct import linked flag",
-            "type": "boolean"
-          },
-          "id": {
-            "description": "Account ID",
-            "type": "string"
-          },
-          "name": {
-            "description": "Account name",
-            "type": "string"
-          },
-          "note": {
-            "description": "Account note",
-            "type": "string"
-          },
-          "on_budget": {
-            "description": "On-budget flag",
-            "type": "boolean"
-          },
-          "transfer_payee_id": {
-            "description": "Transfer payee ID",
-            "type": "string"
-          },
-          "type": {
-            "description": "Account type",
-            "type": "string"
-          },
-          "uncleared_balance": {
-            "description": "Uncleared balance in dollars",
-            "type": "number"
-          }
-        },
-        "required": [
-          "id",
-          "name",
-          "type",
-          "on_budget",
-          "closed",
-          "balance",
-          "cleared_balance",
-          "uncleared_balance",
-          "transfer_payee_id"
-        ],
-        "type": "object"
-      }
-    },
-    "required": [
-      "account"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "action": {
+        "const": "ynab_create_account",
+        "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": false,
+        "properties": {
+          "balance": {
+            "type": "number"
+          },
+          "budget_id": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          },
+          "type": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "budget_id",
+          "name",
+          "type",
+          "balance"
+        ],
+        "type": "object"
+      }
+    },
+    "required": [
+      "dry_run",
+      "action",
+      "request"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "account": {
+        "additionalProperties": false,
+        "properties": {
+          "balance": {
+            "description": "Account balance in dollars",
+            "type": "number"
+          },
+          "cleared_balance": {
+            "description": "Cleared balance in dollars",
+            "type": "number"
+          },
+          "closed": {
+            "description": "Closed flag",
+            "type": "boolean"
+          },
+          "direct_import_in_error": {
+            "description": "Direct import error flag",
+            "type": "boolean"
+          },
+          "direct_import_linked": {
+            "description": "Direct import linked flag",
+            "type": "boolean"
+          },
+          "id": {
+            "description": "Account ID",
+            "type": "string"
+          },
+          "name": {
+            "description": "Account name",
+            "type": "string"
+          },
+          "note": {
+            "description": "Account note",
+            "type": "string"
+          },
+          "on_budget": {
+            "description": "On-budget flag",
+            "type": "boolean"
+          },
+          "transfer_payee_id": {
+            "description": "Transfer payee ID",
+            "type": "string"
+          },
+          "type": {
+            "description": "Account type",
+            "type": "string"
+          },
+          "uncleared_balance": {
+            "description": "Uncleared balance in dollars",
+            "type": "number"
+          }
+        },
+        "required": [
+          "id",
+          "name",
+          "type",
+          "on_budget",
+          "closed",
+          "balance",
+          "cleared_balance",
+          "uncleared_balance",
+          "transfer_payee_id"
+        ],
+        "type": "object"
+      },
+      "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"
+      }
+    },
+    "required": [
+      "account"
+    ],
+    "type": "object"
+  }
+]

Changed4 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"
```

Changed1 schema field changedv0.27.1Jul 12, 2026

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"
+}

Addedv0.26.9May 11, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true), the description discloses the non-obvious two-step preview/confirm safety protocol, including what the preview returns (confirmation_token, confirmation_expires_at) and that the token is short-lived and request-bound. This is exactly the behavioral context a mutating tool needs and it is not derivable from the structured fields.

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 Args/Returns/Examples/write-safety layout is well front-loaded and each section serves a purpose. There is minor redundancy — the Examples block mostly restates the dry_run guidance already given in the Args and write-safety paragraphs.

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 write tool with six parameters, a preview-confirm protocol, and an output schema, the description covers purpose, argument meanings, the mutation workflow, and the return shape. Nothing an agent needs to invoke it correctly — including the ordering of preview versus execute — is missing.

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 17%, so the description must carry the burden — and it does: it documents five of six parameters with types, optionality, defaults, and the full valid enum for type (which the schema lists but does not explain). The sixth parameter, confirmation_token, is covered by the write-safety paragraph explaining its preview semantics and single-use nature.

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

Purpose4/5

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

The description opens with a specific verb+resource statement ("Create a new account in a YNAB budget") and enumerates the account types, so an agent can easily separate it from ynab_list_accounts/ynab_get_account and from the transaction-creating siblings. It loses a point only because it never explicitly contrasts itself with those siblings by name.

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

Usage Guidelines4/5

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

It gives concrete operational guidance: omit budget_id to use the default budget, use dry_run=true to preview, and call without confirmation_token to obtain a short-lived token before executing the identical request. That is a real when-to-use workflow, though it offers no explicit "do not use this when..." exclusions or alternatives.

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

Deploy Server