# Finance MCP tools

> The finance engine is exposed to any MCP client as tools grouped by the stage of the books they serve. Read tools never write; every write tool's description states its preconditions, its refusals and its side effects, and every one is reversible by a named partner tool or by a reopen with a reason. search_tools finds a tool by intent and mcp_health lists the full catalogue; this page is the map.

URL: https://biloh.com.au/docs/reference/finance-mcp-tools
Category: Reference | Audience: agent | Updated: 2026-09-18

## How to read this page

Tools are listed by the stage of the books they serve. **Read** tools never
write. **Write** tools state, in their own descriptions, when to use them,
when not to, the preconditions that must hold, the codes they refuse with,
and exactly which rows they write. Money is integer cents everywhere. Every
response carries `meta.tenant` so an agent can confirm which business it is
acting on; see [write safety and expected tenant](/docs/reference/write-safety-expected-tenant).

`search_tools(query)` finds a tool by intent. `mcp_health` returns the full
catalogue. `get_finance_settings` returns the tenant's finance profile and
registry settings in one read.

## Orientation

| Tool | Class | Use |
| --- | --- | --- |
| `get_bookkeeper_worklist` | read | The one first read: `has_new_work`, counts by stream, contradictions, high-water marks. Advances the marks unless `peek: true` |
| `get_accountant_summary` | read | The weekly summary: envelopes, period status, exceptions, cards awaiting; every block names its source library |
| `get_attention_digest` | read | The operator's cross-business queue, including due obligations, stale feeds and envelope shortfalls |
| `get_finance_settings` | read | Tenant finance profile plus every `finance.*` setting |

## Bank feed

| Tool | Class | Use |
| --- | --- | --- |
| `create_bank_account` | write | Register an account: masked identifier, kind, purpose, opening balance as at a date |
| `update_bank_account` | write | Correct or archive (`is_active: false`) an account |
| `list_bank_accounts` | read | Chained balance, coverage, line count, `chain_intact`, `feed_health` per account |
| `import_bank_csv` | write | Ingest a statement export into a named account; chain-guarded; idempotent |
| `list_bank_transactions` | read | Ingested lines by match state, direction and date window |
| `get_period_completeness` | read | Prove the period's lines tie by running balance; names the first break |
| `ignore_pre_cutover_transactions` | write | Cutover: bulk-mark unmatched lines before the cutover date as pre-Biloh history |

## Money in

| Tool | Class | Use |
| --- | --- | --- |
| `triage_bank_feed` | read/write | Worklist mode: untriaged lines with invoice `candidates` per deposit. Decide mode: apply triage decisions in batch, optionally creating payer rules |
| `get_reconciliation_suggestions` | read | Ranked candidates for credits (invoices) and debits (payables), plus `possible_transfers` |
| `match_bank_credit_to_invoice` | write | Record the deposit as the invoice's payment on the bank value date; learns the payer alias; one deposit to one invoice |
| `link_bank_credit_to_existing_payment` | write | Link a deposit to a payment already recorded, creating no new money |
| `unmatch_reconciliation` | write | Undo a match: void the payment, free the deposit |
| `triage_bank_transaction` / `bulk_triage_bank_transactions` | write | Code a non-invoice line to a reporting category |
| `untriage_bank_transaction` / `ignore_bank_transaction` | write | Reverse a triage; mark a line as not sale income |
| `create_bank_payer_rule` / `apply_bank_payer_rules` / `list_bank_payer_rules` / `deactivate_bank_payer_rule` | write/read | Remember a payer; rules never auto-triage a line whose amount equals an outstanding invoice |
| `get_client_money_story` | read | Deposits that look like a client's, beside their invoices and payments |

## Money out

| Tool | Class | Use |
| --- | --- | --- |
| `record_bill` | write | Record a contractor's multi-line bill against open payables |
| `record_contractor_bill` | write | Backfill door: a bill where no accrual exists yet |
| `record_paid_bill` | write | Record and settle an already-paid bill against its debit in one call |
| `settle_bill_with_bank_debit` | write | Settle a bill with a debit, fanning across payables oldest first; part payments are first class |
| `match_bank_debit_to_payable` | write | Single-payable settlement without a bill |
| `settle_bill_externally` / `settle_payable_externally` | write | Paid outside the feed |
| `reverse_bill_settlement` / `reverse_payable_settlement` / `unmatch_bank_debit` | write | Undo |
| `create_vendor` / `verify_vendor_abn` / `update_vendor` / `list_vendors` | write/read | Suppliers, with GST registration from the ABR |
| `stage_vendor_coding_from_document` | write | Stage a coding from the invoice's own lines; writes no figure |
| `create_vendor_coding_rule` / `apply_vendor_coding_rules` / `list_staged_vendor_codings` | write/read | Deterministic rules that stage codings for repeat suppliers |
| `confirm_vendor_coding` | write | The only door through which a staged coding reaches a report |
| `split_bank_transaction` / `unsplit_bank_transaction` | write | Divide a mixed line into typed splits, GST only where evidenced |
| `attach_bill_document` / `annotate_document` | write | Substantiation: attach the tax invoice; record markings such as business-use percentage |
| `recompute_substantiation` | write | Re-derive every record's evidence state from current thresholds |
| `list_expense_records` / `update_expense_record` | read/write | The substantiation worklist and corrections |
| `create_reporting_category` / `update_reporting_category` / `list_reporting_categories` | write/read | Categories with `pnl_treatment` and `gst_treatment` |

## Shoebox

| Tool | Class | Use |
| --- | --- | --- |
| `create_shoebox_upload_link` | write | A single-use link to snap a receipt from a phone |
| `move_document_to_shoebox` | write | Queue a document Biloh already holds |
| `list_shoebox_items` | read | Waiting receipts with their extracted figures and age |
| `suggest_shoebox_pairings` | read | Offer receipt-to-debit pairs; writes nothing |
| `confirm_shoebox_pairing` | write | Attach the receipt as the debit's evidence; re-derives substantiation |
| `record_shoebox_cash_expense` | write | Exit a receipt as a cash expense that will never hit the feed |

## Transfers and envelopes

| Tool | Class | Use |
| --- | --- | --- |
| `match_transfer_pair` / `unmatch_transfer_pair` / `list_transfer_pairs` | write/read | Pair the two halves of a movement of your own money; reaches no report |
| `get_envelope_targets` | read | Tax set-aside and contractor buffer: target, actual by chained balance, gap |

## Close ladder

| Tool | Class | Use |
| --- | --- | --- |
| `get_period_ladder` | read | Months, quarters and the FY with state: open, closed, reopened, stale; both `label` and `displayLabel` |
| `get_month_end_status` | read | One period's close state plus a live summary |
| `run_period_close` | write | Close a month, quarter or FY; hard completeness gate; optional peer-total variance |
| `run_month_end_close` | write | The month-only predecessor of `run_period_close` |
| `reopen_period` | write | Unlock with a required reason |
| `get_period_reconciliation_view` | read | Two-sided AR and AP view for a window, basis-aware |
| `backfill_period` | write | Bring a period's history in from before Biloh |

## BAS and GST

| Tool | Class | Use |
| --- | --- | --- |
| `get_bas_worksheet` | read | G1, 1A, 1B, net, PAYG slot, exceptions, on the ATO labels |
| `get_gst_position` | read | Net GST for a period |
| `get_sales_gst_report` | read | One row per receipt, cash basis |
| `get_purchases_gst_report` | read | One row per paid bill or coded debit, with evidence state |
| `get_category_totals` | read | A period by reporting category with treatments |
| `get_bank_triage_report` | read | Triaged lines by category or rollup class |

## Reports

| Tool | Class | Use |
| --- | --- | --- |
| `get_profit_and_loss` | read | Cash P&L, ex-GST, with the prior period beside every line |
| `get_balance_sheet` | read | As at any date; equity as the residual; states what it does not hold |
| `get_tpar_report` | read | Taxable Payments Annual Report per subcontractor for an FY |
| `get_aged_payables` | read | AP ageing in buckets |
| `get_depreciation_schedule` | read | The FY's schedule, tying across years by construction |

## Assets

| Tool | Class | Use |
| --- | --- | --- |
| `create_asset` | write | Mint from the debit, a document or by hand; method required |
| `list_assets` | read | The register |
| `record_asset_disposal` | write | Proceeds, date and the computed balancing adjustment |

## Compliance calendar

| Tool | Class | Use |
| --- | --- | --- |
| `list_obligations` | read | BAS, super and TPAR seed themselves with AU due dates on first read |
| `upsert_obligation` | write | Add or correct a renewal; annual cadence self-perpetuates |
| `mark_obligation_lodged` | write | Record lodgement; the receipt document is required |

## Period pack

| Tool | Class | Use |
| --- | --- | --- |
| `generate_period_pack` | write | One ZIP per month, quarter or FY; idempotent while nothing moves; versioned when it does |
| `get_period_pack` | read | Manifest with checksums, composed figures, signed download link |

## Xero mirror

For a business that keeps Xero as its ledger of record, invoices and bills can
be mirrored. Bank lines never come from Xero.

| Tool | Class | Use |
| --- | --- | --- |
| `get_xero_connection_status` / `get_xero_authorize_url` / `disconnect_xero` | read/write | Connection lifecycle |
| `get_xero_mirror_for_entity` / `list_xero_mirror_log` | read | What was mirrored and when |
| `manual_resync_invoice_to_xero` / `manual_resync_payable_to_xero` | write | Re-push one record |

## Invoice-side tools

Invoicing, payments recorded by hand, credits, statements and late fees are
documented separately: [work your invoice list](/docs/how-to/work-your-invoice-list),
[invoice send gates and guards](/docs/reference/invoice-send-gates-and-guards),
[record a cash payment taken on site](/docs/how-to/record-a-cash-payment-taken-on-site).

## Related

- [Finance settings](/docs/reference/finance-settings)
- [Bank import and close refusal codes](/docs/reference/bank-import-and-close-refusal-codes)
- [Closing the books by chat](/docs/explanation/closing-the-books-by-chat)