{"id":"concept:dry-run","kind":"concept","label":"Dry Run","synonyms":["preview","preview-before-write"],"definition":"A dry run is a preview of exactly what a tool would write to the ledger — which accounts, which amounts — before anything is actually posted.","summary":"The informal name for a real, specific mechanism: BalanceMCP's tools take a confirm parameter, defaulting to a preview until it's explicitly set true. A clean preview isn't a guarantee, either — it runs in a separate pass from the actual write, so something can change in between, like an account being archived.","explanation":["A dry run is the general concept of previewing what an action would do before it actually happens, without committing anything. Nearly every tool in BalanceMCP that writes to the ledger — categorizing transactions, posting an entry, reversing one, locking a period — supports exactly this pattern.","Worth being precise about the actual mechanism rather than the informal name: the tools that write to the ledger use a parameter literally called confirm, not \"dryRun.\" Called with confirm left at its default (false), a tool returns a preview of exactly what it would do — the accounts, the amounts, the direction — without writing anything. Called with confirm set to true, it actually performs the write. Every tool that posts, reverses, categorizes, or locks uses this same parameter name deliberately, so a model calling different tools doesn't have to guess between different conventions — the one exception is create_book, which has no confirm parameter at all and creates the book on its first call, since there's no preceding ledger state a preview could check.","A dry run genuinely reduces risk, but it isn't an ironclad guarantee that a subsequent confirm will succeed identically. The preview and the actual write run as two separate passes, not one locked transaction spanning both — something can change in the gap between them, like an account being archived, which can make a clean-looking preview fail differently once actually confirmed.","Practically, a dry run is the moment worth actually reading rather than approving reflexively, especially for a large batch — catching an obviously wrong pattern in the preview costs nothing, while catching the same mistake after confirming means reversing entries instead of simply adjusting the request."],"commonMistakes":["Assuming BalanceMCP's parameter is literally called \"dryRun\" — it's confirm, defaulting to a preview until set true, on every tool that writes to the ledger except create_book, which has no confirm step.","Assuming a clean preview guarantees an identical, successful confirm — the two run as separate passes, and something can change in between.","Approving a large batch's preview reflexively instead of actually reading it — that's the cheap moment to catch a mistake, before it becomes a posted entry."],"category":"ai-mcp","questions":[{"question":"Is \"dry run\" a literal setting I need to pass?","answer":"No — the actual parameter across BalanceMCP's tools is called confirm, defaulting to a preview-only mode until it's explicitly set to true."},{"question":"If a preview looks clean, is the actual write guaranteed to succeed the same way?","answer":"Not quite — the preview and the write run as separate passes, so something can change in between, like an account being archived, which can make the confirm step fail even after a clean preview."}],"url":"/glossary/dry-run","relatedTo":[{"id":"concept:mcp-tool","relationship":"related","weight":0.9,"api":"/api/knowledge/concept%3Amcp-tool"},{"id":"concept:categorization","relationship":"related","weight":0.9,"api":"/api/knowledge/concept%3Acategorization"},{"id":"concept:journal-entry","relationship":"related","weight":0.9,"api":"/api/knowledge/concept%3Ajournal-entry"},{"id":"concept:posting","relationship":"related","weight":0.9,"api":"/api/knowledge/concept%3Aposting"},{"id":"tool:categorize_transactions","relationship":"references","weight":0.7,"api":"/api/knowledge/tool%3Acategorize_transactions"},{"id":"tool:post_journal_entry","relationship":"references","weight":0.7,"api":"/api/knowledge/tool%3Apost_journal_entry"},{"id":"topic:permissions","relationship":"references","weight":0.7,"api":"/api/knowledge/topic%3Apermissions"}],"referencedBy":[{"id":"concept:posting","label":"Posting","url":"/glossary/posting"},{"id":"concept:categorization","label":"Categorization","url":"/glossary/categorization"},{"id":"concept:mcp-client","label":"MCP Client","url":"/glossary/mcp-client"},{"id":"concept:ai-bookkeeping","label":"AI Bookkeeping","url":"/glossary/ai-bookkeeping"}],"license":"https://creativecommons.org/licenses/by/4.0/","attribution":"BalanceMCP — https://balancemcp.com"}