Get the server's loaded configuration.

Returns loaded modules, tool count, book path, debug mode, and version. Use this to verify which tools are available in this session.

Switch the active GnuCash book (multi-book sessions only).

All subsequent tool calls — and the audit/debug logs — operate on the newly-selected book until the next switch. Only present when GNUCASH_BOOK_PATH lists 2+ books.

Read slots (custom metadata) from an account.

Slots are key-value pairs stored on accounts for metadata like APR, credit limit, reward rates, or any custom data.

Args: account: Account ref: full path (e.g., "Liabilities:Credit Cards:Capital One"), %short GUID, or full 32-char GUID. key: Specific slot key to retrieve. If omitted, returns all slots.

Set a custom metadata slot on an account.

Stores a key-value pair on the account. Values are stored as strings. Use for APR, credit limits, reward rates, or any per-account metadata.

Args: account: Account ref: full path (e.g., "Liabilities:Credit Cards:Capital One"), %short GUID, or full 32-char GUID. key: Slot key (e.g., "apr", "credit_limit"). value: Slot value (always stored as string).

Remove a custom metadata slot from an account.

Args: account: Account ref: full path (e.g., "Liabilities:Credit Cards:Capital One"), %short GUID, or full 32-char GUID. key: Slot key to remove.

Read audit log entries for a date.

Returns the human-readable text audit log, led by a Showing X-Y of Z audit entries (date) indicator. Each write operation (CREATE, UPDATE, DELETE, VOID, RECONCILE, etc.) is one entry separated by a blank line. Reads are not logged.

Unlike the row-list tools, the window is anchored to the most recent entry: offset pages backward into history (offset=0 is the newest page), since "what happened lately" is the usual question. limit=0 returns the count only.

Args: log_date: Date to read (YYYY-MM-DD). Defaults to today. limit: Page size (default 50). 0 = count only. offset: Entries to skip back from the most recent (default 0).

Create an on-demand backup of the GnuCash book.

Uses SQLite's online backup API so the snapshot is safe even if the book is being read or written concurrently by GnuCash desktop. Verifies the copy with PRAGMA integrity_check before declaring success; a failed check deletes the bad backup and raises.

Manual backups are kept indefinitely — automatic retention (session / weekly / monthly stages) does not touch them. Use prune_backups(stage="manual") if you want to clean them up explicitly.

The response includes a restore_hint describing the filesystem command to restore from this backup. Restore is a human-run filesystem operation, not an MCP tool — see docs/RESTORE_FROM_BACKUP.md for details.

Args: label: Optional free-text label (sanitized to [A-Za-z0-9_-]) appended to the filename for human context, e.g. "pre-recategorization" or "pre-tax-filing".

List all available backups, newest first.

Leads with a Showing X-Y of Z backups (date range) line, then a compact tab-separated table with one row per backup: stage, timestamp (ISO UTC), age, size (MB), and label (if any). Stages are session / weekly / monthly (automatic retention tiers) and manual (user- invoked, unlimited retention). Page with offset; limit=0 returns the count only.

Args: limit: Page size (default 50, max 250). 0 = count only. offset: 0-indexed first row to return (default 0).

Remove older backups, keeping the most recent N per stage.

Default is dry_run=True — the response shows what WOULD be deleted without touching disk, so the caller can confirm before committing. Pass dry_run=False to actually delete.

When stage is None (default), only auto-retention stages (session / weekly / monthly) are pruned. Manual backups are never auto-pruned; target them explicitly with stage="manual".

Args: keep_last_n: Number of backups to retain per affected stage. Must be >= 0. stage: If set, only prune within this stage. One of session, weekly, monthly, manual. dry_run: When True (default), report only. When False, delete.

List all budgets in the book.

Leads with a Showing X-Y of Z budgets line, then a compact one-line-per-budget format by default. Page with offset; limit=0 returns the count only. Use verbose=true for the full JSON envelope.

Args: verbose: If true, return the full JSON envelope. limit: Page size (default 50, max 250). 0 = count only. offset: 0-indexed first row to return (default 0).

Get full details of a budget including all budget amounts.

Returns a compact text table by default — collapses uniform periods (e.g., "250/mo (all periods)") so the typical 12-cell repeat doesn't dominate the response. Use verbose=true for the full structured periods dict per account.

Args: name: Budget name. verbose: If true, return the full structured dict.

Create a new budget.

Args: name: Budget name (e.g., "2026 Budget"). year: Budget year. Defaults to current year. Ignored when start_date is provided. num_periods: Number of periods. Default 12 (monthly for a year). period_type: Period length: - "monthly" (default) - "quarterly" - "weekly" description: Optional description. start_date: Optional ISO date (YYYY-MM-DD) when the budget's first period begins. When omitted, falls back to January 1 of year. Use this to author a historical budget for comparison against past actuals (e.g. start_date="2024-01-01") or to start mid-year.

Set a budget target for an account.

Args: budget_name: Name of the budget. account: Account ref: full path (e.g., "Expenses:Groceries"), %short GUID, or full 32-char GUID. amount: Monthly budget amount as string (e.g., "500.00"). period: Which period(s) to set: - None or "all": Set same amount for all periods (default) - Integer 0-11: Set specific period (0 = January for yearly budget) - "q1", "q2", "q3", "q4": Set all periods in quarter

Compare actual spending against budget.

Returns a compact text table by default with ⚠ markers on categories exceeding budget. Use verbose=true for the full structured dict.

Args: budget_name: Name of the budget. period: Which period to report: - None: Current period based on today's date (default) - Integer 0-11: Specific period - "ytd": Year to date (all periods up to current) - "all": All periods account: Optional filter to specific account or parent account. include_children: If True and account specified, include child accounts. verbose: If true, return the structured dict.

Delete a budget.

Args: name: Budget name.

Create a new customer.

Args: name: Customer name (e.g., "Acme Corp"). currency: ISO currency code (e.g., "USD", "EUR"). Defaults to book's default currency. notes: Optional notes (max 4096 characters). address: Optional address with keys: name, addr1, addr2, addr3, addr4, phone, fax, email. Each sub-field capped at 1024 characters.

List all customers.

Leads with a Showing X-Y of Z customers line, then a compact one-line-per-customer format by default. Page with offset; limit=0 returns the count only. Use verbose=true for full JSON with guid, address, notes, etc.

Args: active_only: If True, only show active customers. Default True. verbose: If true, return full JSON details for each customer. limit: Page size (default 50, max 250). 0 = count only. offset: 0-indexed first row to return (default 0).

Get details for a specific customer by ID.

Args: id: Customer ID (e.g., "000001"). This is the human-readable ID shown in GnuCash, not the internal GUID.

Create a new vendor.

Args: name: Vendor name (e.g., "Office Depot"). currency: ISO currency code (e.g., "USD", "EUR"). Defaults to book's default currency. notes: Optional notes (max 4096 characters). address: Optional address with keys: name, addr1, addr2, addr3, addr4, phone, fax, email. Each sub-field capped at 1024 characters.

List all vendors.

Leads with a Showing X-Y of Z vendors line, then a compact one-line-per-vendor format by default. Page with offset; limit=0 returns the count only. Use verbose=true for full JSON with guid, address, notes, etc.

Args: active_only: If True, only show active vendors. Default True. verbose: If true, return full JSON details for each vendor. limit: Page size (default 50, max 250). 0 = count only. offset: 0-indexed first row to return (default 0).

Get details for a specific vendor by ID.

Args: id: Vendor ID (e.g., "000001"). This is the human-readable ID shown in GnuCash, not the internal GUID.

Create a new employee.

Employee has no notes field (unlike Customer and Vendor). Address shape is identical.

Args: name: Employee name (e.g., "Jane Smith"). currency: ISO currency code (e.g., "USD", "EUR"). Defaults to book's default currency. address: Optional address with keys: name, addr1, addr2, addr3, addr4, phone, fax, email. Each sub-field capped at 1024 characters.

List all employees.

Leads with a Showing X-Y of Z employees line, then a compact one-line-per-employee format by default. Page with offset; limit=0 returns the count only. Use verbose=true for full JSON with guid, address, etc.

Args: active_only: If True, only show active employees. Default True. verbose: If true, return full JSON details for each employee. limit: Page size (default 50, max 250). 0 = count only. offset: 0-indexed first row to return (default 0).

Get details for a specific employee by ID.

Args: id: Employee ID (e.g., "000001"). This is the human-readable ID shown in GnuCash, not the internal GUID.

Update an existing customer.

Mutates only the fields supplied; everything else stays. Existing invoices/bills are not retroactively changed — currency here is the customer's default trading currency for future documents.

Args: id: Customer ID (e.g., "000001"). name: New display name. currency: New default ISO currency code (e.g., "EUR"). notes: New notes. Pass "" to clear. active: false to deactivate (archive without deleting); true to reactivate. address: Partial address dict — keys name, addr1..addr4, phone, fax, email. Merges onto the existing address (creating one if absent). To clear a sub-field, pass an empty string explicitly for that key.

Update an existing vendor.

Same semantics as update_customer.

Args: id: Vendor ID (e.g., "000001"). name: New display name. currency: New default ISO currency code. notes: New notes. Pass "" to clear. active: false to deactivate; true to reactivate. address: Partial address dict (see update_customer).

Update an existing employee.

Employee has no notes column — parameter omitted accordingly. Otherwise identical to update_customer.

Args: id: Employee ID (e.g., "000001"). name: New display name. currency: New default ISO currency code. active: false to deactivate; true to reactivate. address: Partial address dict (see update_customer).

Create a new billing term.

Args: name: Billterm name (e.g., "Net 30"). due_days: Number of days until payment is due. Default 30. description: Optional description. discount_days: Days within which early discount applies. discount_percent: Early payment discount percentage (e.g., "2" for 2%).

List all billing terms.

Leads with a Showing X-Y of Z billterms line, then a compact one-line-per-term format by default. Page with offset; limit=0 returns the count only. Use verbose=true for full JSON with guid, discount details, etc.

Args: verbose: If true, return full JSON details for each billing term. limit: Page size (default 50, max 250). 0 = count only. offset: 0-indexed first row to return (default 0).

Create a new sales-tax table.

A taxtable holds one or more entries. Each entry contributes either a percentage rate or a flat-value surcharge routed to a specific GL account (ASSET for input-tax credit, LIABILITY for output sales tax payable). Multi-entry composites (e.g., GST 5% + PST 7%) produce multiple tax splits per line at posting time.

Args: name: Taxtable name, unique within the book (e.g., "CA Sales 7.25%", "BC GST+PST"). entries: List of {type, amount, account} dicts. type: "value" or "percentage". amount: positive decimal as string. Percentages are the rate ("5.00" = 5%, not "0.05"). account: account path, %short-guid, or full GUID. Must be ASSET or LIABILITY type. All entries on a single taxtable must reference accounts in the same commodity.

Example: create_taxtable( name="BC GST+PST", entries=[ {"type": "percentage", "amount": "5.00", "account": "Liabilities:GST Payable"}, {"type": "percentage", "amount": "7.00", "account": "Liabilities:PST Payable"}, ], )

List all sales-tax tables.

Leads with a Showing X-Y of Z taxtables line. Compact format (default): one line per taxtable with name, entry count, and per-entry rate→account routing. Page with offset; limit=0 returns the count only. Verbose: full JSON with resolved account paths and refcount.

Args: verbose: If true, return full JSON for each taxtable. limit: Page size (default 50, max 250). 0 = count only. offset: 0-indexed first row to return (default 0).

Get full details for one sales-tax table.

Returns guid, name, refcount (count of Entry rows referencing it — voided invoices still count), and the resolved entry list with account paths.

Args: name: Taxtable name.

Update a sales-tax table's name and/or entries.

Diff-style response: only changed fields are returned.

Entry replacement on a taxtable that's already in use is destructive to FUTURE entries' tax math. Existing posted invoices retain their original splits (splits are stored, not derived), but new entries on any document will use the replacement entries' rates. When refcount > 0 and entries is given, force=True is required to proceed.

Args: name: Current taxtable name. new_name: New name (optional). entries: Replacement entry list (optional). Same shape and validation as create_taxtable. force: Required to replace entries when the taxtable is already referenced by document entries.

Delete a sales-tax table.

Refuses when any Entry row references the taxtable (computed via SQL on the entries table). Voided invoices still pin their taxtables — voided entry rows persist for audit-trail purposes. Remove or re-assign referencing entries first.

Args: name: Taxtable name.

Create a customer invoice.

Args: customer_id: Customer ID (e.g., "000001"). date_opened: Date in ISO format (YYYY-MM-DD). Defaults to today. notes: Optional notes. currency: ISO currency code. Defaults to the customer's currency, falling back to the book's default. Pass explicitly to override. term: Billterm name (e.g., "Net 30"). Optional. invoice_id: Custom invoice number (e.g., "INV-2026-001"). If omitted, auto-generates from the book's invoice counter. job_id: Optional Job ID. When set, groups the invoice under the named job. The job must belong to the same customer and be a customer-job (created with owner_type='customer'). Use create_job first to define the job, then attach invoices to it via this parameter.

Create a vendor bill.

Args: vendor_id: Vendor ID (e.g., "000001"). date_opened: Date in ISO format (YYYY-MM-DD). Defaults to today. notes: Optional notes. currency: ISO currency code. Defaults to the vendor's currency, falling back to the book's default. Pass explicitly to override. term: Billterm name (e.g., "Net 30"). Optional. bill_id: Custom bill number (e.g., "BILL-2026-001"). If omitted, auto-generates from the book's bill counter. job_id: Optional Job ID. When set, groups the bill under the named job. The job must belong to the same vendor and be a vendor-job.

Add a line item to a customer invoice.

The invoice must not be posted yet. Entries represent individual goods or services being billed.

Args: invoice_id: Invoice ID (e.g., "000001"). account: Income account path (e.g., "Income:Sales"). description: Line item description. quantity: Quantity as decimal string (e.g., "1", "2.5"). price: Unit price as decimal string (e.g., "100.00"). taxtable: Optional taxtable name. When given, the line contributes tax components per the taxtable's entries at posting time. Multi-entry taxtables (e.g., GST+PST) produce one tax split per entry. tax_included: If true, price is the gross (tax-included) value; pretax extracted at posting. If false (default), price is pre-tax and tax adds on top. notes: Optional per-line notes (max 4096 bytes) — detail that doesn't belong on the printed description line. action: Optional line-type label (GnuCash convention: "Hours", "Material", "Project").

Add a line item to a vendor bill.

The bill must not be posted yet. Entries represent individual goods or services being billed.

Args: bill_id: Bill ID (e.g., "000001"). account: Expense account path (e.g., "Expenses:Office Supplies"). description: Line item description. quantity: Quantity as decimal string (e.g., "1", "2.5"). price: Unit price as decimal string (e.g., "50.00"). taxtable: Optional taxtable name. For vendor bills, the tax component typically routes to an ASSET account (input-tax credit receivable) per the taxtable's entries. tax_included: If true, price is gross; pretax extracted at posting. If false (default), tax adds on top. notes: Optional per-line notes (max 4096 bytes). action: Optional line-type label (GnuCash convention: "Hours", "Material", "Project").

Create an employee expense voucher.

A voucher is the document an employee submits for reimbursement of out-of-pocket business expenses. It behaves like a vendor bill: post creates the obligation (debit expense accounts, credit A/P), pay settles it from a cash account.

Args: employee_id: Employee ID (e.g., "000001"). date_opened: Date in ISO format (YYYY-MM-DD). Defaults to today. notes: Optional notes. currency: ISO currency code. Defaults to the employee's currency, falling back to the book's default. term: Billterm name (e.g., "Net 30"). Optional — vouchers rarely use payment terms. voucher_id: Custom voucher number. If omitted, auto-generates from the book's voucher counter.

Add a line item to an employee expense voucher.

The voucher must not be posted yet. Each entry is typically a separate expense category (meals, supplies, travel). Account must be EXPENSE or ASSET.

Args: voucher_id: Voucher ID (e.g., "000001"). account: Expense account path (e.g., "Expenses:Meals & Entertainment"). description: Line item description. quantity: Quantity as decimal string (e.g., "1"). price: Unit price as decimal string (e.g., "42.50"). taxtable: Optional taxtable name. Same semantics as add_bill_entry. tax_included: If true, price is gross; pretax extracted at posting. notes: Optional per-line notes (max 4096 bytes) — e.g. receipt reference or attendee list. action: Optional line-type label (GnuCash convention: "Hours", "Material", "Project").

Delete an unposted employee expense voucher.

Automatically removes associated entries. Posted vouchers cannot be deleted — unpost first via unpost_invoice, then delete.

Args: id: Voucher ID (e.g., "000001"). Preferred parameter name — matches get_invoice / post_invoice / etc. voucher_id: Legacy alias for id. Accepted for back-compat; pass exactly one of id or voucher_id.

Create a credit note against a customer invoice or vendor bill.

A credit note reverses part or all of a posted invoice while preserving the original posting in the audit trail. At post time, posting direction reverses: customer credit notes debit Income / credit A/R (reducing receivables); vendor credit notes debit A/P / credit Expense (reducing payables). Settled either by refund (pay_invoice) or by netting against an outstanding invoice (apply_credit_note).

Use add_credit_note_entry to add line items, then post_invoice to post.

Args: owner_id: Customer or vendor ID (e.g., "000001"). owner_type: "customer" or "vendor". Employees are not supported (GnuCash desktop has no UI for employee credit notes; use unpost_invoice + edit on the voucher to amend an employee reimbursement). applies_to_invoice_id: Optional source invoice / bill ID. Must belong to the same owner and use the same currency. Highly recommended for audit trail. Can be omitted for floating credit notes that will be applied later. date_opened: ISO date (YYYY-MM-DD). Defaults to today. notes: Free-text notes (e.g., reason for the credit). currency: ISO currency code. Inherited from source invoice when applies_to_invoice_id is given; otherwise from owner's currency or book default. term: Billterm name. Rarely used for credit notes. credit_note_id: Custom ID. Auto-generated from the shared invoice/bill counter when omitted.

Add a line item to a credit note.

Mirrors add_invoice_entry / add_bill_entry but validates the target is in fact a credit note (the slot flag is the gate). Account type rules match the non-credit twin: INCOME for customer credit notes, EXPENSE/ASSET for vendor credit notes. Prices stay positive — the credit-note flag inverts posting direction at post time, not at entry-add time.

Args: credit_note_id: Credit note ID (e.g., "000032"). account: Account path appropriate for the owner type (INCOME for customer, EXPENSE/ASSET for vendor). description: Line item description. quantity: Quantity as decimal string. price: Unit price as decimal string. owner_type: Optional "customer" or "vendor" disambiguator for ID collisions. Usually omitted. taxtable: Optional taxtable name. Same semantics as add_invoice_entry; the credit-note flag inverts tax-split direction at posting time so a refunded tax-inclusive sale produces a debit to the tax-payable account. tax_included: If true, price is gross; pretax extracted at posting. notes: Optional per-line notes (max 4096 bytes) — e.g. the reason this line is being credited. action: Optional line-type label (GnuCash convention: "Hours", "Material", "Project").

Net a posted credit note against a posted invoice or bill from the same owner. No cash moves — the credit balance transfers between lots on the same A/R or A/P account.

This is the most common credit-note settlement path: the bookkeeper issues a credit note against an overcharge, then nets it against the next invoice from that customer (or applies it to an outstanding bill on the vendor side). Use pay_invoice instead when the credit note will be settled by sending or receiving cash.

Args: credit_note_id: The credit note to apply (must be posted). applies_to_invoice_id: The target invoice/bill (must be posted, same owner, same currency, same A/R or A/P post account). amount: Decimal-string amount to apply, in the document currency. Defaults to min(credit_note_ remaining, target_remaining) — apply as much as possible. apply_date: ISO date for the netting transaction. Defaults to today. owner_type: Optional 'customer' or 'vendor' disambiguator for ID collisions.

Delete an unposted credit note.

Validates the target is a credit note before deletion. Posted credit notes cannot be deleted — unpost first via unpost_invoice, then delete.

Args: id: Credit note ID. Preferred parameter name — matches get_invoice / post_invoice / etc. credit_note_id: Legacy alias for id. Accepted for back-compat; pass exactly one of id or credit_note_id. owner_type: Optional "customer" or "vendor" disambiguator for ID collisions.

List invoices and/or vendor bills.

Leads with a Showing X-Y of Z invoices (date range) line, then a compact one-line-per-invoice format by default. Page with offset; limit=0 returns the count only. Use verbose=true for full JSON with GUIDs, dates, notes, etc.

Args: owner_type: Filter by type: "customer" for invoices, "vendor" for bills, or omit for all. status: Filter by status: "posted" or "open", or omit for all. verbose: If true, return full JSON details. limit: Page size (default 50, max 250). 0 = count only. job_id: Filter to invoices grouped under a specific job — useful for the "what's part of this engagement?" listing pattern. offset: 0-indexed first row to return (default 0).

Get full details for an invoice or bill, including line items.

Works for both customer invoices and vendor bills. Returns all entries with quantities, prices, and totals.

Args: id: Invoice or bill ID (e.g., "000001"). This is the human-readable ID, not the internal GUID. owner_type: Filter by type: "customer" for invoices, "vendor" for bills. Useful when an invoice and bill share the same ID (independent counters).

Post a customer invoice or vendor bill.

Posting creates a transaction in the A/R or A/P account and makes the invoice official. Once posted, entries cannot be added.

For a foreign-currency document, the exchange rate is etched at posting and cannot be updated retroactively. If the latest price for the invoice currency is more than 7 days from the post date (the GNUCASH_FX_GUARD_DAYS window), posting is refused with a stale_fx_rate error — run create_price for a rate near the post date, then retry, or pass force=True to post with the stale rate (recorded in the response and audit log as fx_stale/"forced"). A rate beyond the 90-day staleness cap cannot be forced.

Args: id: Invoice or bill ID (e.g., "000001"). post_account: A/R or A/P account path (e.g., "Assets:Accounts Receivable"). post_date: Date in ISO format (YYYY-MM-DD). Defaults to today. due_date: Payment due date (YYYY-MM-DD). Optional. description: Description for the posting transaction. Optional. owner_type: "customer" or "vendor" for disambiguation when IDs collide. force: Override the stale-FX-rate guard and post with a 7–90 day stale rate. Default False.

Reverse a posted invoice or bill.

Deletes the posting transaction and lot, and clears the invoice's posted-state metadata. The invoice returns to "open" state and can be edited or re-posted. Refuses if the invoice has any payments applied — void payments first, then unpost.

Args: id: Invoice or bill ID (e.g., "000001"). owner_type: "customer" or "vendor" for disambiguation when IDs collide.

Record a payment against a posted invoice or bill.

Creates a payment transaction from the specified bank/cash account to the invoice's A/R or A/P account. Partial payments are supported.

For cross-currency payments where the rate moved between post-date and pay-date, a realized FX gain/loss split is booked. Pass fx_account to control routing; otherwise the server picks the unique INCOME/EXPENSE account whose leaf name matches "fx", "forex", "foreign exchange", "currency gain/loss", "exchange gain/loss", or "currency translation". When zero or multiple match, the canonical Income:Foreign Exchange Gain/Loss is used (auto-created if absent), and an fx_notice is returned listing ambiguous candidates so you can pass fx_account explicitly next time.

For invoices with early-payment-discount terms (e.g., "2/10 Net 30" = 2% off if paid within 10 days), pass apply_discount=True to settle via discount. The tool validates that the invoice has discount terms, the payment date is within the discount window, and the shortfall matches the expected discount on pre-tax principal. Each failure mode rejects with a specific error rather than silently downgrading to a partial payment. discount_account controls routing the same way fx_account does (auto-resolves to Expenses:Sales Discounts for customer payments, Income:Purchase Discounts Taken for vendor bill payments).

Args: id: Invoice or bill ID (e.g., "000001"). payment_account: Bank or cash account for payment (e.g., "Assets:Checking"). amount: Payment amount as decimal string (e.g., "500.00"). payment_date: Payment date (YYYY-MM-DD). Defaults to today. description: Description for the payment transaction. Optional. owner_type: "customer" or "vendor" for disambiguation. fx_account: Optional INCOME or EXPENSE account to receive realized FX gain/loss (cross-currency payments only). Accepts a full path, %short GUID, or full 32-char GUID. apply_discount: When True, treat this payment as the final settlement and absorb the early-payment discount from the invoice's billterm. Default False — explicit opt-in. Hard-rejects on credit notes (refunds don't take discounts). discount_account: Optional INCOME or EXPENSE account to receive the discount split. Auto-resolves when omitted. Accepts full path, %short GUID, or full 32-char GUID. force: Override the stale-FX-rate guard. A cross-currency payment etches the rate at pay time; if the latest price is 7–90 days from the payment date the payment is refused with stale_fx_rate unless force=True (the override is recorded as fx_stale/"forced"). A rate beyond the 90-day cap cannot be forced. memo: Optional memo for the bank-account split (e.g., check number or wire reference). description names the whole transaction; memo annotates the cash movement.

Delete an unposted customer invoice.

Automatically removes associated entries (line items). Posted invoices cannot be deleted — void them or issue a credit note instead.

Args: id: Invoice ID (e.g., "000001" or "INV-2026-001"). Preferred parameter name — matches get_invoice / post_invoice / etc. invoice_id: Legacy alias for id. Accepted for back-compat; pass exactly one of id or invoice_id.

Delete an unposted vendor bill.

Automatically removes associated entries (line items). Posted bills cannot be deleted — void them or issue a credit note instead.

Args: id: Bill ID (e.g., "000001" or "BILL-2026-001"). Preferred parameter name — matches get_invoice / post_invoice / etc. bill_id: Legacy alias for id. Accepted for back-compat; pass exactly one of id or bill_id.

Delete a customer with no invoices.

Customers with any invoices (posted or unposted) cannot be deleted. Delete the invoices first, then delete the customer.

Args: customer_id: Customer ID (e.g., "000001").

Delete a vendor with no bills.

Vendors with any bills (posted or unposted) cannot be deleted. Delete the bills first, then delete the vendor.

Args: vendor_id: Vendor ID (e.g., "000001").

Delete an employee.

Employees in the 1.3.0 release have no associated documents; the delete proceeds unconditionally after slot cleanup.

Args: employee_id: Employee ID (e.g., "000001").

Create a job for a customer or vendor.

A job groups invoices (or bills) from one counterparty under a project-level container. Useful when a single customer has multiple distinct engagements (e.g., 'API Rewrite' and 'Q3 Maintenance') that should be reported on separately even though invoices flow to the same A/R.

Args: owner_id: Customer or vendor ID (e.g., "000001"). owner_type: "customer" or "vendor". Employees are not supported (no GnuCash desktop UI for employee jobs). name: Human-readable job name (e.g., "API Rewrite"). reference: Optional reference string (PO number, project code).

List jobs, optionally filtered.

Leads with a Showing X-Y of Z jobs line; page with offset, or pass limit=0 for the count only.

Args: owner_type: Filter by "customer" or "vendor". Omit for all. owner_id: Filter by specific customer or vendor ID (requires owner_type). active_only: If True (default), exclude inactive jobs. verbose: If True, return full JSON dicts; otherwise compact tab-separated rows. limit: Page size (default 50, max 250). 0 = count only. offset: 0-indexed first row to return (default 0).

Get a job's details by ID.

Returns name, owner, active state, plus a count + IDs list of every invoice/bill linked to the job.

Args: job_id: Job ID (e.g., "000001").

Update a job's name, reference, or active state.

Any subset of fields can be passed; unspecified fields are left unchanged. Returns a diff-style response.

Args: job_id: Job ID. name: New name (optional). reference: New reference (optional). active: New active flag — pass False to deactivate a completed job without deleting it (preserves history).

Per-job summary: billed / paid / outstanding totals across all linked invoices, plus the per-invoice breakdown.

Totals are returned as totals_by_currency (a dict keyed by ISO currency code) so the same shape works whether the job's invoices share a currency or span multiple. Both posted and unposted (draft) invoices are included — drafts contribute their face value as billed + outstanding with paid=0, so the report shows the full pipeline.

Args: job_id: Job ID (e.g., "000001").

Delete a job.

Refuses by default when invoices/bills are linked to the job (data-loss prevention). force=True re-parents every linked invoice back to its underlying customer or vendor before deleting the job row, preserving invoice history. Use update_job(active=False) instead if you want to keep the job in place but mark the project done.

Args: job_id: Job ID. force: If True, re-parent linked invoices instead of refusing. Default False.

Get all posted invoices/bills with outstanding balances.

Leads with a Showing X-Y of Z invoices (date range) line, then a compact one-line-per-doc format by default with action columns (due date, days past due, currency, BILL tag, owner). Sorted most-overdue-first so the bookkeeper sees the urgent items at the top. Page with offset; limit=0 returns the count only.

Use verbose=true for full JSON with original_amount / amount_paid / amount_due breakdown — the shape pay_invoice workflows expect.

Args: owner_type: Filter by "customer" or "vendor". Omit for all. customer_id: Filter by specific customer ID. vendor_id: Filter by specific vendor ID. verbose: If true, return full JSON details. limit: Page size (default 50, max 250). 0 = count only. offset: 0-indexed first row to return (default 0).

Get spending breakdown by vendor for a period.

Analyzes posted vendor bills to show total billed, total paid, and outstanding amounts per vendor.

Returns a compact aligned text table by default. Use verbose=true for the full structured dict (programmatic consumers).

Args: start_date: Start of period (YYYY-MM-DD). end_date: End of period (YYYY-MM-DD). vendor_id: Optional filter to a specific vendor. verbose: If true, return the structured dict. group_by: Optional "month", "quarter", or "year" — split the range into sub-period columns of total billed per vendor and return a multi-period TSV table. Overrides verbose.

Get a compact overview of the entire GnuCash book.

Returns book path, currency, account structure, transaction counts, key balances, net worth, commodities, and scheduled transactions in a single text response. Use this first to orient yourself.

List all accounts in the GnuCash chart of accounts.

Leads with a Showing X-Y of Z accounts line, then a compact one-line-per-account format by default. Page with offset; limit=0 returns the count only. Use verbose=true for full JSON with guid, type, commodity, etc.

To FIND an account without paging the whole chart, pass query — a case-insensitive substring matched against each account's full path and description (e.g. query="grocer" or query="4930" on a numbered chart). Results emit %short GUIDs that every account-taking tool accepts. For searching transactions by text or amount, use search_transactions.

Args: root: Filter to a subtree (e.g., "Expenses" for expense accounts only). verbose: If true, return full JSON details for each account. limit: Page size (default 50, max 250). 0 = count only. offset: 0-indexed first row to return (default 0). query: Case-insensitive substring filter on account path/description. Combines with root.

Get details for a specific account by name.

Args: name: Account ref: full path (e.g. 'Assets:Bank:Checking'), %short GUID, or full 32-char GUID

Get the balance of an account as of a specific date.

Defaults to today's date — future-dated transactions (scheduled payments, accrued interest) are excluded. To project a balance forward including future entries, pass an explicit as_of_date past today.

Args: account_name: Account ref: full path (e.g. 'Assets:Bank:Checking'), %short GUID, or full 32-char GUID as_of_date: Date in ISO format (YYYY-MM-DD). Defaults to today.

List transactions with optional filters.

Leads with a Showing X-Y of Z transactions (date range) line so a truncated view is never mistaken for the whole set. Page with offset; limit=0 returns the count only.

Compact format (default):

• Unfiltered: DATE<TAB>guid<TAB>Description<TAB>splits

• Filtered by account (register form): DATE<TAB>guid<TAB>±Amount<TAB>Description<TAB>other splits Column 3 is the signed impact on the filtered account; that account is dropped from the splits column.

Transactions with more than 4 splits collapse to the top 3 by |value| plus +N more — call get_transaction for the full breakdown.

Args: account: Filter by account name (switches output to register form) start_date: Start date in ISO format (YYYY-MM-DD) end_date: End date in ISO format (YYYY-MM-DD) limit: Page size (default 50, max 250). 0 = count only. offset: 0-indexed first row to return (default 0). verbose: If true, return full JSON details for each transaction.

Get details for a specific transaction by GUID.

Args: guid: Transaction GUID (32-character hex string, or 8+ char prefix)

Create a new transaction with splits. Splits must balance to zero.

Each split: account (full path, required), amount (required, in transaction currency), quantity (required when account commodity differs from transaction currency), memo (optional), action (optional). amount and quantity are decimal strings (e.g. "94.87") — never raw JSON numbers, which would lose precision on non-dyadic decimals.

FIELD TARGETING — the annotation fields, one job each, in GnuCash-register visibility order:

• description: the clean name ("Chevron 0090706 Portland"). Always visible.

• notes: what the purchase WAS, when the description alone doesn't say ("Fuel, road trip to Portland"). Visible in the register's double-line view — this is the annotation humans read. Interpret; don't transcribe.

• split memo (bank/card leg): the RAW statement line as provenance ("Withdrawal ACH TRAVELERS TYPE: PER INSUR…"). Visible only in expanded split view — evidence, not narrative.

• split action: the typed KIND of movement, one word. Matters most on investment legs, where desktop convention (and the Advanced Portfolio report) expects "Buy" / "Sell" / "Dividend"; bank legs may use "Wire" / "ATM" / "Interest". Skip it for ordinary spending.

When duplicate detection surfaces candidates (either rejecting the write with status: "rejected" or returning alongside a successful create), duplicates in the response is a newline-separated TSV string, not a list of dicts. Columns::

confidence<TAB>guid<TAB>date<TAB>amount<TAB>cur<TAB>description<TAB>signals

Confidence is HIGH (all three signals match) or MEDIUM (two of three). Signals is a three-char code: position 0 description, position 1 amount (±$1 tolerance), position 2 date (±2 days); D/A/D for match, - for miss.

Args: description: Transaction description. splits: List of split dicts (see above). Omit to auto-fill from the most recent matching-description transaction. transaction_date: ISO date (YYYY-MM-DD). Defaults to today. currency: ISO currency code. Defaults to book's default. notes: What the purchase was (see FIELD TARGETING above). check_duplicates: Run duplicate detection. Default True. force_create: Create even if HIGH-confidence duplicates found. dry_run: Validate + dupe check only; don't write.

Create MANY transactions in one atomic command (bulk entry).

INPUT — transactions is a TSV block: a header row, then one row per transaction. The HEADER DECLARES THE LAYOUT. Base form: splits are (amount, account) column PAIRS, repeated as wide as a transaction needs::

ref<TAB>date<TAB>description<TAB>amt1<TAB>acct1<TAB>amt2<TAB>acct2...
1<TAB>2026-05-21<TAB>Gas<TAB>-54.19<TAB>Assets:Checking<TAB>54.19<TAB>Expenses:Auto:Fuel

Two opt-in extensions, each activated by naming it in the header (legacy headers parse exactly as before):

• PER-SPLIT MEMOS — declare memo split columns; splits become (amount, account, memo) TRIPLES::

  ref<TAB>date<TAB>description<TAB>amt1<TAB>acct1<TAB>memo1<TAB>amt2<TAB>acct2<TAB>memo2
  1<TAB>2026-05-21<TAB>Gas<TAB>-54.19<TAB>Assets:Checking<TAB>card #4471<TAB>54.19<TAB>Expenses:Auto:Fuel

  Empty memo cells mid-row keep their tabs; a row may simply END once its last split's amount and account are present (trailing memo/qty cells are read as empty — no placeholder tabs needed, as above).

• PER-TRANSACTION NOTES — declare a notes column directly after description::

  ref<TAB>date<TAB>description<TAB>notes<TAB>amt1<TAB>acct1...

  FIELD TARGETING for statement entry: description is the clean name; notes is what the purchase WAS — interpreted, not transcribed — and is what humans see in GnuCash's double-line register; the bank leg's memo is where the RAW statement line goes (provenance, visible only in expanded split view). Prefer filling notes whenever the description alone doesn't tell the story.

• PER-TRANSACTION CURRENCY — declare a cur column after description (before or after notes); an ISO code cell sets THAT ROW's transaction currency, an empty cell keeps the book default::

  ref<TAB>date<TAB>description<TAB>cur<TAB>amt1<TAB>acct1<TAB>amt2<TAB>acct2
  1<TAB>2026-07-15<TAB>USD Card Payment<TAB>USD<TAB>-500<TAB>Assets:USD Checking<TAB>500<TAB>Liabilities:USD Card

  With cur, the row's amt cells are in that currency and must balance in it. Use it when NO leg is in the book's default currency (a USD-to-USD transfer inside a CNY book needs no invented CNY values and no qty). Splits on accounts of any OTHER commodity still need qty. The currency must already exist in the book, and cur cannot combine with an auto-fill row.

• PER-SPLIT QUANTITY — declare qty split columns for splits whose ACCOUNT commodity differs from the book default (investment shares, foreign-currency accounts)::

  ref<TAB>date<TAB>description<TAB>amt1<TAB>acct1<TAB>qty1<TAB>amt2<TAB>acct2<TAB>qty2
  1<TAB>2026-07-01<TAB>VFIFX Purchase<TAB>-505.17<TAB>Assets:Checking<TAB><TAB>505.17<TAB>Assets:401k:VFIFX<TAB>7.7936

  amount stays in the book's default currency (the transaction currency — batch never changes that); qty is the amount in the account's own commodity. An EMPTY qty cell means the account uses the default currency (quantity == amount). A non-default-commodity account with an empty qty rejects that row.

• PER-SPLIT ACTION — declare act split columns for GnuCash's typed movement tag ("Buy"/"Sell"/"Dividend" on investment legs — desktop convention; "Wire"/"ATM" on bank legs). Same group mechanics as memo/qty; empty cells skip it. Rarely needed for plain spending.

All extensions combine; when several split fields are declared, the header's FIRST group fixes their order (e.g. amt, acct, memo, qty).

AUTO-FILL — a row with NO split cells at all (ends right after description/notes) reproduces the most recent transaction with the same description — splits, memos, and quantities included — exactly like calling create_transaction without splits::

1<TAB>2026-07-01<TAB>Rent
2<TAB>2026-07-01<TAB>Netflix

Auto-filled rows are marked auto_filled_from:<guid> in the results reason column; a row whose description matches nothing rejects ("no matching transaction to auto-fill from"). Use dry_run=true to preview what a batch of auto-fills would book. Perfect for recurring monthly entries. Transaction notes are NOT copied from the source (notes are often time-bound — "first appearance, investigate" must not replicate); supply a notes cell when the new instance needs one.

• ref: YOUR correlation key per row (e.g. 1, 2, 3), unique within the batch. It is echoed back so you can match results to what you sent; the server never reuses or interprets it.

• date: ISO YYYY-MM-DD. amount/qty: decimal STRINGS (never raw JSON numbers). Each transaction needs

  =2 splits balancing to zero in the default currency. Rows may differ in width (2 splits vs 3).

• The transaction currency is always the book default — for a transaction denominated in another currency, use create_transaction with its currency parameter.

BEHAVIOR — one book-open, one atomic save:

• A STRUCTURAL error (unbalanced, unknown account, bad pairs) aborts the WHOLE batch by default; nothing is written. Pass on_error="skip" to write the good rows and reject only the bad ones.

• A duplicate rejects ONLY its row; force=True overrides all blocking duplicates (as in create_transaction). dry_run=True validates + screens without writing.

OUTPUT — a JSON envelope of two TSV tables joined by ref:

• results (always): ref, status, txn_guid, dup_count, reason. status is created | rejected | would_create (dry_run); reason is a code like duplicate_detected or the validation message.

• duplicates (only when matches exist): ref, confidence, guid, date, amount, description, signals — the columns create_transaction emits, keyed back to the offending ref. Σ(dup_count) equals the duplicates row count.

Args: transactions: The TSV block described above. force: Override ALL blocking (HIGH) duplicates this batch. dry_run: Validate + screen, write nothing. on_error: "abort" (default) or "skip" for structural errors.

Search transactions by description, memo, notes, or amount.

Compact format (default): DATE<TAB>guid<TAB>Description<TAB>splits Transactions with more than 4 splits collapse to the top 3 by |value| plus +N more — call get_transaction for the full breakdown. Leads with a Showing X-Y of Z transactions line; page with offset, or pass limit=0 for the count.

Args: query: Search query string. For amount, supports: exact ("100"), greater (">100"), less ("<100"), range ("100-200") field: Field to search: 'description', 'memo', 'notes', or 'amount' limit: Page size (default 50, max 250). 0 = count only. offset: 0-indexed first row to return (default 0). verbose: If true, return full JSON details for each transaction.

Create a new account in the chart of accounts.

Args: name: Account name (e.g., "AI Subscriptions"). account_type: One of ASSET, BANK, CASH, CREDIT, EQUITY, EXPENSE, INCOME, LIABILITY, MUTUAL, STOCK, RECEIVABLE, PAYABLE. parent: Parent account ref (full path, %short GUID, or full 32-char GUID). Omit for top-level. description: Optional description. placeholder: Container-only account. Default False. commodity: ISO currency code ("USD") or stock/fund symbol ("VTSAX"). Defaults to book's default currency. commodity_namespace: "CURRENCY" (default), "FUND", or an exchange ("NASDAQ", "NYSE"). Required with non-currency commodities. notes: Optional free-text notes (max 4096 bytes). Shows in GnuCash desktop's account editor Notes field.

Update an existing account's properties.

Args: name: Account ref to update (full path e.g. "Expenses:Groceries", %short GUID, or full 32-char GUID) new_name: New name for the account (just the leaf name, not full path) description: New description placeholder: New placeholder status (true = container only) account_type: New account type (e.g., "CREDIT", "BANK"). Only changes within the same debit/credit polarity are allowed — e.g., LIABILITY to CREDIT, ASSET to BANK. Cross-polarity changes (e.g., ASSET to LIABILITY) are blocked. notes: New notes (max 4096 bytes; shared with GnuCash desktop's Notes field). Pass "" to clear.

Move an account to a new parent in the hierarchy.

Args: name: Account ref to move (full path e.g. "Expenses:Old:Account", %short GUID, or full 32-char GUID) new_parent: New parent account ref (full path, %short GUID, or full 32-char GUID)

Delete an account from the chart of accounts.

Safeguards prevent deletion if the account has children or transactions.

Args: name: Account ref to delete (full path, %short GUID, or full 32-char GUID)

Delete one transaction by GUID — or several in one call.

Safeguards prevent deletion if a transaction has reconciled splits (force=true overrides) or is an invoice's posting record (unpost_invoice first).

Pass a LIST of GUIDs to delete several in one book open / one save. The batch is all-or-nothing: every guid is validated before anything is deleted, so a bad guid rejects the whole call with nothing removed. Response for a list is {status, count, transactions: [{guid, description}]}; a single guid returns the single-object shape as before.

Args: guid: Transaction GUID (32-char hex or 8+ char prefix), or a list of them. force: Allow deleting transactions with reconciled splits.

Update an existing transaction — or broadcast to several.

Pass a LIST of GUIDs to apply the SAME supplied values to every listed transaction in one book open / one save (all-or-nothing) — the batch-annotation case: one note across 35 related entries, one call. splits stays single-transaction. For per-row DIFFERENT values, use update_transactions.

Args: guid: Transaction GUID (32-character hex string, or 8+ char prefix), or a list of them description: New transaction description (optional) transaction_date: New date in ISO format YYYY-MM-DD (optional) splits: List of split updates with 'account' and 'amount' (optional). Must match existing splits by account name and balance to zero. For cross-currency splits, include 'quantity' (amount in account's commodity). Include 'memo' to set that split's memo (omit to leave it unchanged). amount/quantity are decimal strings (e.g. "94.87"). notes: New transaction notes (optional). Pass empty string to clear. force: Allow modifying transactions with reconciled splits — required for split changes AND for moving the date of a transaction with reconciled splits (a date move shifts it out of its reconciled statement period).

Update MANY transactions with per-row values (bulk edit).

INPUT — updates is a TSV block: header guid plus any of description, notes, date (at least one), then one row per transaction::

guid<TAB>description<TAB>notes
56926ac2<TAB>PayPal Credit Payment<TAB>Resolved — card payment
7f0fc117<TAB><TAB>Netflix subscription, $22.10/mo

An EMPTY cell leaves that field UNCHANGED — this batch can annotate but never clear (clearing is update_transaction with notes="", deliberately single-transaction). Splits and memos are not updatable here (replace_splits).

One book open, one save; on_error="abort" (default) sinks the batch on any bad row, "skip" keeps good rows. Date moves on transactions with reconciled splits are rejected per row unless force=true (they shift the transaction out of its reconciled statement period). Returns a results TSV keyed by your input guids. For the SAME value across many transactions, update_transaction with a guid list is cheaper than repeating rows.

Replace all splits in a transaction with a new set.

Replace all splits in a transaction with a completely new set. The transaction's currency, description, date, and notes are preserved. New splits must balance to zero.

A new split that reproduces an existing one (same account, amount, and quantity) is an UNCHANGED leg: it keeps the old split's memo (supply a memo to override) and its reconcile state. So recategorizing the expense leg of a reconciled bank transaction is safe — resubmit the bank leg as-is and only the changed leg resets.

Args: guid: Transaction GUID (32-character hex string, or 8+ char prefix) splits: Complete new set of splits. Each split needs: - 'account' (required): Account ref — full path, %short GUID, or full 32-char GUID - 'amount' (required): Value in transaction currency, as a decimal string - 'quantity' (optional): Amount in account's commodity, as a decimal string. Required if account commodity differs from transaction currency. - 'memo' (optional): Split memo force: Required only when the replacement would CHANGE a reconciled split (or remove splits from lots) — unchanged reconciled legs are preserved without it.

List all commodities (currencies, stocks, etc.) in the book.

Leads with a Showing X-Y of Z commodities line, then a compact one-line-per-commodity format by default. Page with offset; limit=0 returns the count only. Use verbose=true for full JSON with fraction, latest prices, etc.

THE PRICE-UPDATE WORK LIST: stale_days=30, held_only=true returns exactly the commodities needing fresh quotes, each marked Nd stale or no price on file. Look the quotes up, then record them all in one create_prices call.

Args: verbose: If true, return full JSON details for each commodity. limit: Page size (default 50, max 250). 0 = count only. offset: 0-indexed first row to return (default 0). stale_days: Only commodities whose latest market price is at least this many days old, including never-priced ones, excluding the book default currency. Omit for the unfiltered list. held_only: Only commodities some real account is denominated in. Filters AND-combine.

Create a new commodity (stock, mutual fund, etc.).

Args: mnemonic: Symbol (e.g., "VTSAX"). Unique within namespace. fullname: Human-readable name. namespace: "FUND" (default) for mutual funds, "NASDAQ"/"NYSE"/ "AMEX" for stocks, or any custom string. fraction: Smallest fractional unit. 1 = whole units, 100 = 2 decimals, 10000 = 4 decimals (default, shares), 1000000 = 6 decimals (crypto). cusip: Optional CUSIP/ISIN identifier.

Record MANY prices in one call (bulk quote entry).

INPUT — prices is a TSV block: a header row, then one row per price. Required columns ref, commodity, date, value; optional columns extend the header IN ORDER: ns, cur, source, type (stop anywhere; rows may end early; empty cells take defaults)::

ref<TAB>commodity<TAB>date<TAB>value<TAB>cur<TAB>source
1<TAB>VTSAX<TAB>2026-07-21<TAB>148.32<TAB><TAB>web:yahoo
2<TAB>EUR<TAB>2026-07-21<TAB>1.0845<TAB><TAB>web:ecb

• ref: your correlation key, echoed in results.

• ns: commodity namespace; empty auto-resolves when the symbol is unambiguous across namespaces.

• cur: quote currency; empty = book default.

• source: where the quote came from (provenance — default "user:price"); type: nav/last/bid/ask.

Per-row semantics are create_price's exactly: an existing price with the same commodity/currency/date/source is UPDATED in place (status: updated), never duplicated. One book open, one save, on_error="abort" (default) sinks the whole batch on any bad row; dry_run=true previews as would_create / would_update.

The companion work list: list_commodities(stale_days=30, held_only=true).

Record a price for a commodity (stock, NAV, exchange rate).

An existing price with the same commodity/currency/date/source is updated rather than duplicated.

Args: commodity: Symbol (e.g., "VTSAX"). namespace: Commodity namespace (e.g., "FUND", "NASDAQ"). value: Price per unit as decimal string (e.g., "250.45"). currency: ISO currency code. Defaults to the book's default currency — so create_price(commodity="USD", value="7.30") on a CNY-default book stores "1 USD = 7.30 CNY" (the natural reading). Pass explicitly for cross-currency pairs that don't involve the book default. date: ISO date (YYYY-MM-DD). Defaults to today. price_type: "nav" (default, mutual funds), "last", "bid", "ask", or "unknown". source: Source identifier. Default "user:price".

Delete a single price entry.

Identifies the price by (commodity, namespace, date). Pass source to disambiguate when multiple prices exist on the same commodity+date (e.g. one user-entered and one fetched from a feed).

Args: commodity: Symbol (e.g., "VTSAX", "USD", "EUR"). namespace: Namespace (e.g., "FUND", "CURRENCY"). date: ISO date (YYYY-MM-DD) of the price to delete. source: Optional source tag (e.g., "user:price", "user:yfinance"). Required when multiple prices exist on the same commodity+date.

Get price history for a commodity.

Leads with a Showing X-Y of Z prices (date range) line, then a compact aligned text table by default. Page with offset; limit=0 returns the count only. Use verbose=true for the full structured envelope (prices list, showing, total, offset, count).

Args: commodity: Symbol of the commodity (e.g., "VTSAX"). namespace: Namespace of the commodity (e.g., "FUND"). start_date: Optional start date filter (YYYY-MM-DD). end_date: Optional end date filter (YYYY-MM-DD). currency: Optional currency filter (e.g., "USD"). limit: Page size (default 50, max 250). 0 = count only. verbose: If true, return the structured dict. offset: 0-indexed first row to return (default 0).

Get the most recent price for a commodity.

Args: commodity: Symbol of the commodity (e.g., "VTSAX"). namespace: Namespace of the commodity (e.g., "FUND"). currency: Currency for the price. Defaults to the book's default currency. Pass explicitly to get a price quoted in a non-default currency.

Returns: JSON with date, value, type, and source of most recent price. Returns null if no price exists.

Create a new lot for cost basis tracking.

Lots group investment purchases for tracking cost basis and calculating capital gains when selling.

Args: account: Account ref for the investment account: full path (e.g., "Assets:Investments:VTSAX"), %short GUID, or full 32-char GUID. title: Lot identifier (e.g., "VTSAX 2026-01-15 purchase"). notes: Optional notes.

List all lots for an investment account.

Leads with a Showing X-Y of Z lots line, then a compact one-line-per-lot format by default. Page with offset; limit=0 returns the count only. Use verbose=true for full JSON with guid, title, notes, etc.

Args: account: Account ref (full path, %short GUID, or full 32-char GUID). include_closed: If True, include fully-sold lots. Default False. verbose: If true, return full JSON details for each lot. limit: Page size (default 50, max 250). 0 = count only. offset: 0-indexed first row to return (default 0).

Get detailed information about a lot.

Args: guid: Lot GUID (or 8+ char prefix).

Returns: JSON with lot details including all splits: - title, notes, is_closed - splits: list of all splits with date, quantity, value - summary: total quantity, cost basis, cost per share

Assign a transaction split to a lot.

Use after creating a buy/sell transaction to link the investment account split to its lot for cost basis tracking.

Args: split_guid: GUID of the split (from transaction's investment account). 8+ char prefix accepted. lot_guid: GUID of the lot (or 8+ char prefix).

Workflow: 1. create_lot("Assets:VTSAX", "VTSAX Jan 2026") 2. create_transaction(...buy 10 shares...) 3. assign_split_to_lot(investment_split_guid, lot_guid)

Calculate potential or actual capital gain for a lot.

If shares and sale_price provided, calculates hypothetical gain. Otherwise uses lot's current state and latest price.

Args: lot_guid: Lot GUID (or 8+ char prefix). shares: Optional number of shares to calculate for. Defaults to all remaining shares. sale_price: Optional sale price per share. Defaults to latest price for the commodity.

Mark a lot as closed.

Use when a lot is fully sold but wasn't automatically marked closed, or to manually close a lot with zero shares.

Args: guid: Lot GUID (or 8+ char prefix).

Note: Lots are automatically marked closed when their quantity reaches zero through assigned splits. This tool is for manual cleanup.

Set the reconciliation state for a split.

Args: split_guid: GUID of the split to update (32-character hex string, or 8+ char prefix) state: New reconcile state: 'n' (new), 'c' (cleared), 'y' (reconciled) reconcile_date: Date in ISO format (YYYY-MM-DD). Required for 'y', defaults to today.

Per-account reconciliation table behind the dashboard's aggregate counts — answers "WHICH accounts are never reconciled / dormant / behind?"

One line per reconcilable account with activity, bucketed exactly as the dashboard classifies them: behind (most-behind first, with pending-split counts), never, current, dormant ($0, fully reconciled, idle), and excluded (opted out via the account's no_reconcile slot — the right setting for loans, escrow payables, and other statement-less accounts: set_account_slot(account, "no_reconcile", "1"). Reporting-only; reconcile tools still work on excluded accounts).

Args: verbose: Full JSON rows instead of compact TSV lines. limit: Page size (default 50, max 250). 0 = count only. offset: 0-indexed first row to return.

Get unreconciled splits for an account.

Leads with a Showing X-Y of Z splits indicator, then one line per split, then a summary footer reflecting the full unreconciled set (so the headline is honest even when individual lines are clipped). Page with offset; limit=0 returns the count only.

Use verbose=true for full JSON with split GUIDs, amounts, totals, and the showing indicator as a structured field.

Args: account: Account ref: full path (e.g. 'Assets:Bank:Checking'), %short GUID, or full 32-char GUID as_of_date: Only include splits on or before this date (YYYY-MM-DD) verbose: If true, return full JSON details. Default compact one-line format. limit: Page size (default 50, max 250). 0 = count only. offset: 0-indexed first row to return (default 0).

Reconcile splits against a statement balance.

SIGN CONVENTION: statement_balance is the ACCOUNT's balance in GnuCash's signs — for liability accounts (credit cards) a $5,000 owed balance is "-5000", not "5000".

Two modes:

• Targeted (split_guids=[...]): reconcile exactly the listed splits (SPLIT guids from get_unreconciled_splits, not transaction guids). Use when statement and book disagree and you need to pick a subset.

• Bulk (reconcile_all=true): reconcile every unreconciled split dated on or before through_date (default: statement_date — a statement reconciliation is bounded by the statement). One call, no GUID round-trip.

Both modes verify the resulting reconciled balance ties to statement_balance before mutating; mismatch rejects with the discrepancy amount.

TYPICAL STATEMENT FLOW (credit card or bank): batch-enter the statement's transactions (create_transactions), then reconcile_all with the statement's closing date and balance. Multi-month catch-up: enter all months in one batch, then one reconcile_all per statement, oldest first — the through_date default keeps each sweep inside its own statement.

Args: account: Account ref: full path (e.g. 'Assets:Bank:Checking'), %short GUID, or full 32-char GUID statement_date: Statement ending date (YYYY-MM-DD) statement_balance: Expected balance from statement (as string, e.g., '1234.56') split_guids: List of split GUIDs to reconcile (targeted mode). Omit for bulk mode. reconcile_all: When true, reconcile all unreconciled splits up to through_date. through_date: Date filter for bulk mode (YYYY-MM-DD); defaults to statement_date.

Void a transaction (proper accounting void, not delete).

Voiding preserves the transaction for audit purposes but zeroes out all split values. Use this instead of delete when you need to maintain an audit trail.

Args: guid: Transaction GUID to void (32-character hex string, or 8+ char prefix) reason: Reason for voiding (required for audit trail)

Restore a voided transaction.

Restores original split values and removes void markers.

Args: guid: Transaction GUID to unvoid (32-character hex string, or 8+ char prefix)

Get spending breakdown by expense category for a period.

Returns a compact aligned text table by default. Use verbose=true for the full structured dict (programmatic consumers, plotting).

Args: start_date: Start of period (YYYY-MM-DD) end_date: End of period (YYYY-MM-DD) depth: Hierarchy depth for grouping (1 = top-level categories, 2 = subcategories) verbose: If true, return the structured dict. group_by: Optional "month", "quarter", or "year" — split the range into sub-period columns and return a multi-period TSV table (category rows, one column per period plus Total and Avg). Overrides verbose.