Reconcile an account

Goal: make sure YNAB agrees with your bank, find the cause when it does not, and mark the account reconciled once it does.

Before you start: the balance your bank shows today, and writes enabled to mark the account reconciled (the diagnosis works read-only).

Tool: reconcile_account. Prompt: reconcile.

The conversation

1. Ask, with the bank’s balance.

   You: My bank shows 3,440.80 on my checking account. Does YNAB agree?

2. The agent compares. It calls reconcile_account with {"plan_id": "last-used", "account_id": "acc-checking", "bank_balance": 3440.80}. avenir-mcp sums the account’s cleared transactions (those the bank has shown) and compares. They differ, so nothing is written:

   reconcile_account — difference found

   {
     "status": "difference_found",
     "message": "YNAB's cleared balance differs from the bank by 112.30. Nothing was changed. Check explained_by, uncleared and possible_duplicates with the user; call again once fixed, or with adjust=true to record the gap as an adjustment.",
     "account": "Checking",
     "analysis": {
       "account_id": "acc-checking",
       "bank_balance": 3440.8,
       "cleared_balance": 3328.5,
       "working_balance": 3328.5,
       "difference": 112.3,
       "to_reconcile_count": 54,
       "uncleared_count": 0,
       "uncleared": [],
       "explained_by": [],
       "possible_duplicates": [
         [
           "tx-055",
           "tx-056"
         ]
       ]
     },
     "adjustment": null,
     "confirmation": null,
     "operation_id": null
   }

3. The agent explains the gap.

   Claude: YNAB counts 71.86 more than the bank. Two identical Market Fresh payments of 71.86 on 19 September look like one import that came twice.

   The answer offers three leads: explained_by (a pending transaction whose amount is exactly the difference), uncleared (what the bank has not shown yet), and possible_duplicates (same amount and merchant, at most 3 days apart, over the last 60 days).

4. You fix the cause — here, delete the duplicate in YNAB.

5. Ask again. When the balances match, avenir-mcp previews the reconciliation: every cleared transaction of the account becomes reconciled. You confirm; it is applied in one request and journaled.

When the gap cannot be explained

Sometimes a small difference stays: a fee never imported, an old error. Only if you ask for it, the agent calls again with adjust=true:

• a transaction Balance adjustment of the difference is created on the account, dated today, in Ready to Assign, with the memo Entered by reconcile_account;
• then the account is reconciled, adjustment included.

Caution

An adjustment hides a problem instead of solving it. avenir-mcp never makes one on its own, and the evaluation checks that an agent asked “don’t change anything” does not either.

Undo

undo_operation puts every transaction it reconciled back to cleared and deletes the adjustment, if one was made. See Undo a change.

Statuses

status	Meaning
difference_found	balances differ; nothing written; read analysis
nothing_to_do	balances match and nothing is left to reconcile
confirmation_required	balances match (or adjust was asked); waiting for your yes
applied	reconciled; operation_id to undo
declined	you said no; nothing written

How the comparison works: Reconciliation.