ynab-mcpb

Overview Schema Source Related Servers Discussions Admin

ynab_reconcile_account

Idempotent

Reconcile a YNAB account against bank CSV transactions by matching entries, detecting discrepancies, and optionally applying bulk create, update, or unclear actions after preview.

Instructions

Guided account reconciliation: match bank CSV transactions to YNAB, detect discrepancies, and optionally execute bulk create/update/unclear operations.

Args:

budget_id (string, optional): Budget UUID. Omit to use the default budget.
account_id (string, required): Account UUID to reconcile.
csv_file_path or csv_data (string, required): Bank export file path or inline CSV text.
statement_balance (number, required): Ending balance from the bank statement (dollars). For credit cards and other liability accounts, pass a negative value (e.g. -6143.27 means you owe $6,143.27).
statement_end_date (string, optional): Statement closing date (YYYY-MM-DD). Filters CSV and triggers balance verification. Auto-detected from CSV if omitted.
match_strictness (string, optional): Matching sensitivity — "loose" (more matches), "normal" (default), or "strict" (fewer false positives).
sign_convention (string, optional): How to treat CSV amount signs — "auto" (default, detects from data), "invert" (negate all amounts), "as_is" (use amounts unchanged). Useful when auto-detection fails for liability accounts.
dry_run (boolean, optional): Preview actions without executing. Default: true.
auto_create_transactions (boolean, optional): Auto-create missing transactions. Default: false.
auto_update_cleared_status (boolean, optional): Auto-mark matched transactions as cleared. Default: false.
auto_unclear_missing (boolean, optional): Auto-mark statement-missing cleared transactions as uncleared when reconciliation remains unbalanced. Default: false.
max_suggestions_in_output (number, optional): Limit unmatched items and suggestions shown in the human report. Default: 20.

Returns: human-readable reconciliation narrative + structured JSON (unmatched_bank, unmatched_ynab, suggestions, execution_summary when actions are performed).

Examples:

Preview reconciliation: set dry_run=true (default)
Execute: set dry_run=false and explicitly enable the write flags you want, e.g. auto_update_cleared_status=true

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	Default
`dry_run`	No
`csv_data`	No
`budget_id`	No
`account_id`	Yes
`csv_format`	No
`csv_file_path`	No
`sign_convention`	No		auto
`match_strictness`	No		normal
`auto_adjust_dates`	No
`statement_balance`	Yes
`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.
`statement_end_date`	No
`date_tolerance_days`	No
`auto_unclear_missing`	No
`auto_create_transactions`	No
`max_suggestions_in_output`	No
`auto_update_cleared_status`	No

Output Schema

Name	Required	Description
`human`	Yes
`structured`	Yes
`confirmation_token`	No	Preview only: single-use token that executes this exact request when passed back as confirmation_token.
`confirmation_expires_at`	No	Preview only: when confirmation_token expires (ISO 8601).

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv0.32.0Nov 7, 2026

addedInput schema / properties / statement_end_date / format
```
Added value: +"date"
```

addedOutput schema / properties / confirmation_expires_at

Added value: +{
+  "description": "Preview only: when confirmation_token expires (ISO 8601).",
+  "format": "date-time",
+  "type": "string"
+}

addedOutput schema / properties / confirmation_token

Added value: +{
+  "description": "Preview only: single-use token that executes this exact request when passed back as confirmation_token.",
+  "type": "string"
+}

Changed7 schema fields changedv0.31.0Oct 29, 2026

addedInput schema / additionalProperties
```
Added value: +false
```

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

addedOutput schema / properties / structured / properties / errors

Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedOutput schema / properties / structured / properties / operations

Added value: +{
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "error": {
+        "type": "string"
+      },
+      "operation": {
+        "additionalProperties": false,
+        "properties": {
+          "changesDate": {
+            "type": "boolean"
+          },
+          "clearedDelta": {
+            "maximum": 9007199254740991,
+            "minimum": -9007199254740991,
+            "type": "integer"
+          },
+          "kind": {
+            "enum": [
+              "create",
+              "update",
+              "unclear",
+              "reconcile"
+            ],
+            "type": "string"
+          },
+          "payload": {
+            "additionalProperties": {},
+            "propertyNames": {
+              "type": "string"
+            },
+            "type": "object"
+          },
+          "reason": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "kind",
+          "payload",
+          "reason",
+          "changesDate",
+          "clearedDelta"
+        ],
+        "type": "object"
+      },
+      "status": {
+        "enum": [
+          "planned",
+          "applied",
+          "uncertain",
+          "skipped"
+        ],
+        "type": "string"
+      },
+      "transaction_id": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "operation",
+      "status"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

Changed28 schema fields changedv0.29.1Oct 26, 2026
- removedInput schema / properties / csv_format / properties / amount_column / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "number"
-  }
-]
```
- addedInput schema / properties / csv_format / properties / amount_column / type
```
Added value: +[
+  "string",
+  "number"
+]
```
- removedInput schema / properties / csv_format / properties / credit_column / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "number"
-  }
-]
```
- addedInput schema / properties / csv_format / properties / credit_column / type
```
Added value: +[
+  "string",
+  "number"
+]
```
- removedInput schema / properties / csv_format / properties / date_column / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "number"
-  }
-]
```
- addedInput schema / properties / csv_format / properties / date_column / type
```
Added value: +[
+  "string",
+  "number"
+]
```
- removedInput schema / properties / csv_format / properties / debit_column / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "number"
-  }
-]
```
- addedInput schema / properties / csv_format / properties / debit_column / type
```
Added value: +[
+  "string",
+  "number"
+]
```
- removedInput schema / properties / csv_format / properties / description_column / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "number"
-  }
-]
```
- addedInput schema / properties / csv_format / properties / description_column / type
```
Added value: +[
+  "string",
+  "number"
+]
```
- removedOutput schema / properties / structured / properties / suggestions / items / properties / candidates / items / properties / ynab_transaction / properties / categoryName / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / structured / properties / suggestions / items / properties / candidates / items / properties / ynab_transaction / properties / categoryName / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / properties / structured / properties / suggestions / items / properties / candidates / items / properties / ynab_transaction / properties / memo / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / structured / properties / suggestions / items / properties / candidates / items / properties / ynab_transaction / properties / memo / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / properties / structured / properties / suggestions / items / properties / candidates / items / properties / ynab_transaction / properties / payee / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / structured / properties / suggestions / items / properties / candidates / items / properties / ynab_transaction / properties / payee / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / properties / structured / properties / suggestions / items / properties / ynab_transaction / properties / categoryName / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / structured / properties / suggestions / items / properties / ynab_transaction / properties / categoryName / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / properties / structured / properties / suggestions / items / properties / ynab_transaction / properties / memo / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / structured / properties / suggestions / items / properties / ynab_transaction / properties / memo / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / properties / structured / properties / suggestions / items / properties / ynab_transaction / properties / payee / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / structured / properties / suggestions / items / properties / ynab_transaction / properties / payee / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / properties / structured / properties / unmatched_ynab / items / properties / categoryName / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / structured / properties / unmatched_ynab / items / properties / categoryName / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / properties / structured / properties / unmatched_ynab / items / properties / memo / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / structured / properties / unmatched_ynab / items / properties / memo / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / properties / structured / properties / unmatched_ynab / items / properties / payee / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / structured / properties / unmatched_ynab / items / properties / payee / type
```
Added value: +[
+  "string",
+  "null"
+]
```

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.6/5.0

Behavior5/5

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

Annotations only say non-read-only, idempotent, non-destructive, open-world; the description goes well beyond by explaining that dry_run defaults to true, that all auto_* write flags default to false, that a short-lived single-use confirmation_token gates execution, and that liability accounts may need a negative balance or an inverted sign convention. This is exactly the mutation-safety context annotations cannot convey.

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 with purpose, then a scannable Args list, Returns, Examples, and a Write-safety block, so an agent can find the decision-relevant parts quickly. The args enumeration is long but justified by the near-empty schema; a few entries (budget_id, account_id) restate the obvious.

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, nested-object, mutating tool with an output schema (so return values need not be spelled out), the description covers the reconciliation lifecycle, the two-phase confirmation gate, and the risk flags an agent must set deliberately. The only real hole is csv_format, which can typically be inferred by auto-detection given the sign_convention fallback described.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With schema description coverage at 6%, the description carries most of the burden and does so for the consequential params: statement_balance sign rules for credit cards, statement_end_date auto-detection and balance verification, match_strictness levels, sign_convention modes, and the meaning of each auto_* flag. Gaps remain for csv_format (a nested 8-field object), auto_adjust_dates, and date_tolerance_days, which are undocumented in both places.

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 a specific verb phrase and scope: match bank CSV transactions to YNAB, detect discrepancies, and optionally execute bulk create/update/unclear operations. This distinguishes it from the plain CRUD siblings (ynab_create_transactions, ynab_update_transactions) by framing it as a guided reconciliation workflow.

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

Usage Guidelines4/5

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

The Examples and 'Write safety' sections give a concrete when/how: call without confirmation_token to preview, then re-issue the identical request with the token to execute, and explicitly enable write flags. It does not name sibling alternatives for individual transaction edits, but the preview-then-execute workflow is unambiguous.

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

Deploy Server