categorize_transactionsWritesTurn bank transactions into real, balanced bookkeeping
You have a pile of imported transactions and you need each one recorded against the right account — rent as rent, materials as materials — as a proper double-entry journal entry, not just a label.
This is the tool that closes the loop between "imported" and "actually bookkept." For each transaction, you (or your assistant) picks one account for the whole amount, or splits it across several — a single Costco charge that's half supplies and half meals, for instance, split as two lines that sum back to the original amount. Behind the scenes, this posts a real balanced journal entry: the bank side mirrors the transaction's own sign, and the category side takes the opposite, the same double-entry logic an accountant would use by hand.
You can hand this tool a whole batch — dozens of transactions in one call — and it treats each one independently. If one transaction can't be posted (a bad amount, a locked period, a mismatched account), that one lands in the response's "skipped" list with a specific reason, and the rest of the batch still goes through. Nothing silently fails and nothing takes the whole batch down with it.
Always preview before confirming. Left at its default, this tool shows you the exact journal lines it would post — which account, which amount, on which side — without writing anything. Only when you say to go ahead does it actually post. That preview is where you catch a miscategorized split before it becomes an entry you have to reverse.
What this does not do
- A locked period blocks posting for any transaction dated in it — that shows up as a skip with a reason, not a silent failure. Because this tool always dates the entry on the transaction's own date, and a lock can never move backward, a transaction dated inside a locked period stays unposted permanently through this tool; recording the same effect after the lock takes a manual post_journal_entry instead.
- Splits are checked for arithmetic (they must sum to the transaction amount) but not for whether the split makes business sense — that judgment is still yours.
Arguments
| Name | Type | Required | What it is |
|---|---|---|---|
bookId | uuid | Required | — |
items | object[] | Required | — |
confirm | boolean | Required | — |
Generated from the tool definition, so it cannot describe arguments the tool does not accept. Unrecognised arguments are rejected rather than ignored.
Common questions
- What happens if I categorize a transaction to the wrong account?
- Use reverse_entry on the resulting journal entry. That undoes the posting and puts the original transaction back in the inbox, unposted, ready to categorize again correctly.
- Can I split one transaction across multiple categories?
- Yes — give it splits instead of a single account, with each split as a positive amount. The amounts must add up to exactly the transaction's total.
- Why did some transactions in my batch get skipped instead of posted?
- Each transaction is checked independently. One with a bad amount, a locked period, or some other issue lands in "skipped" with a specific reason, while everything else in the same batch still posts normally.
- Do I have to categorize transactions one at a time?
- No — hand the assistant a whole batch at once. It previews and posts each one on its own, so a batch of fifty behaves the same as a batch of one, just faster.