Briefcase

View saved version →

---
name: document-submission
description: Submit a bill, receipt, bank statement or supplier statement to a Briefcase client, choosing between direct upload, a browser upload link and the client's forwarding email, then track processing to the resulting transaction. Use when the user shares a document or asks to upload, send or file something into Briefcase.
---

# Submitting documents to Briefcase

## Choose the client

Resolve the client with `briefcase_list_clients` and confirm it with the user when the name is ambiguous. Ask for a business or property only when the client has more than one (`briefcase_get_reference_data` with `kind: businesses` or `properties`).

## Prepare the upload

Call `briefcase_create_document_upload` with the file name, MIME type, size if known, and the user's note (for example "Pay from the deposit account" or "Split 60/40 with the Manchester office").

When the user attached the file in the conversation and your host passes attachments to tools (ChatGPT does), pass it as `file`. Briefcase downloads it itself and `next_step` says the file is already in Briefcase: go straight to `briefcase_submit_document` with the `upload_id` and a fresh `idempotency_key`.

Otherwise the response gives three routes:

1. **You can transfer the file.** `PUT` the original bytes to `upload_url` with the returned headers, then call `briefcase_submit_document` with the `upload_id` and a fresh `idempotency_key`.
2. **You cannot transfer the file.** Give the user `browser_upload_url`. They open it, sign in, check the client and note, choose the file and press Upload. The link expires after one hour and only accepts the prepared file type.
3. **Email.** Give the user `forwarding_email` and tell them to put the note in the email body.

Never fabricate file contents and never submit a file the user did not provide.

## Track processing

`briefcase_submit_document` returns an operation. Poll `briefcase_get_operation` no more than once every few seconds until it reaches a final state, then report:

- the transaction, bank statement or supplier statement that was created, with its status;
- an archive as duplicate or not-a-transaction, with the reason. A created transaction marked `archived: true` was archived by duplicate detection; `briefcase_get_transaction` shows status `ARCHIVED` and a `POSSIBLE_DUPLICATE` warning naming the original;
- a failure, with the message, and suggest re-uploading a clearer copy.

On Autopilot clients a submitted document may publish automatically. Say so before submitting when `briefcase_get_client` shows Autopilot is on.

## Retries and refusals

Retry a failed `briefcase_submit_document` with the same `idempotency_key`; Briefcase will not create a second candidate. A `FORBIDDEN` result means the user cannot upload for this client or assistant changes are paused. `VALIDATION_ERROR` on file type or size means the document must go through the app or email instead.

View saved version →

---
name: expense-claims
description: Group a claimant's receipts into an expense claim in Briefcase, add or remove receipts, check the claim's state and publish it with a preview first. Use when the user asks about employee or director expenses, reimbursing out-of-pocket costs, or what is still waiting to be claimed.
---

# Expense claims in Briefcase

An expense claim bundles unpublished receipts paid personally by one claimant, so the business owes that person rather than a supplier. Creating and editing claims needs the expense claim create permission; publishing needs expense claim publish. `FORBIDDEN` means the user lacks one of them or assistant changes are paused.

## Find what to claim

- `briefcase_list_expense_claims` and `briefcase_get_expense_claim` show existing claims, their receipts and whether they are published.
- `briefcase_list_transactions` with `awaiting_review: true` finds unpublished receipts. Confirm with the user which ones the claimant paid personally; do not guess from the supplier name.
- `briefcase_get_reference_data` with `kind: claimants` gives the claimant contacts.

## Build the claim

1. `briefcase_create_expense_claim` with the `transaction_ids`, the claimant as `supplier_id`, the `claim_date` and a fresh `idempotency_key`. All receipts must share one currency; a mismatch returns `VALIDATION_ERROR`, so split them into separate claims.
2. `briefcase_add_claim_transactions` adds more unpublished receipts to a claim that is not yet published.
3. `briefcase_remove_claim_transaction` takes one receipt back out of an unpublished claim.

Fix a receipt's own coding with `briefcase_update_transaction` before publishing (see the transaction review skill).

## Publish

1. `briefcase_publish_expense_claim` with `mode: preview`. Summarise the claimant, claim date, currency, total, the destination in the ledger and any blockers.
2. `claim_date`, `currency` and `claimant_contact_id` override the stored values only when the user asks. For Xero, `publish_destination` and `bills_to_pay_status` choose how the claim lands; for QuickBooks, `quickbooks_publish_destination`.
3. Execute only after the user agrees, with the `preview_id`, `mode: execute` and a fresh `idempotency_key`.

Publishing posts the claim to the ledger as money owed to the claimant. Say so before executing, and read the claim back with `briefcase_get_expense_claim` afterwards.

View saved version →

---
name: financial-close-review
description: Review a Briefcase client's period close. Check the working paper for what is left to clear and which balance sheet accounts are reconciled and signed off, then review and maintain prepayments, deferred income, accruals and fixed asset depreciation with the close trackers, drafting schedules and adjustments and publishing them with a preview first. Use when the user asks about month-end, year-end, whether a period is ready to close, reconciliation or sign-off status, prepayment or accrual schedules, depreciation, or what is left to post for a period.
---

# Financial close review in Briefcase

Schedules need the FINANCIAL_CLOSE permission in Briefcase. Working papers need the Ledger view permission and only work for Briefcase Ledger clients. If a call returns `FORBIDDEN`, tell the user which permission is missing rather than trying another tool.

## Start with the working paper

For "is this period ready to close" or "what is left for month-end", read the working paper before the schedules.

1. `briefcase_get_working_paper` for the client. It lists recent working papers newest first and details the latest; pass a `working_paper_id` from that list for another period. For a Xero or QuickBooks client it returns `UNSUPPORTED_CAPABILITY`, so send the user to Working papers in Briefcase.
2. Lead with the period (`start_date` to `target_date`), whether it is open or closed, and who closed it.
3. Then what is left to clear:
   - `clearing_the_period.blockers`: each has a `kind`, the bank account and a count. `STATEMENT_COVERAGE_GAP` means statements are missing for part of the period, so request or upload them (document submission skill). `UNRECONCILED_TRANSACTIONS` means bank lines still need matching in Briefcase. `PENDING_BANK_STATEMENTS` means uploaded statements are still being processed. `OPENING_BALANCE_NOT_SET` and `FEED_UNHEALTHY` need fixing in the Briefcase app (set the opening balance, reconnect the feed).
   - `open_client_requests`: paperwork and statements still awaited from the client.
   - `pending.unpublished_invoice_count`: bills and receipts dated in the period but not yet published (transaction review skill). `pending.draft_adjustment_count`: draft schedules and accruals (publish them below).
4. Then the balance sheet: give `balance_sheet.summary`, then name every unreconciled account and every account with `changed_since_sign_off: true`. The latter was signed off at `ledger_balance_at_sign_off` and now stands at `closing_balance`, so it needs reconciling again. For signed-off accounts, say who signed off (`reconciled_by`) and when, and quote any `difference` with its `difference_reason`. Dormant accounts are counted in `dormant_accounts_left_out`, not listed.

The assistant cannot reconcile accounts, sign them off or close a working paper. Those stay with the accountant in Briefcase, so point the user to Working papers in the app for them.

## Read schedules before you write

1. `briefcase_get_close_tracker` for the client and period. Explain the grid: opening balance, movement in the period, closing balance, and which periods are posted, due or paused.
2. `briefcase_list_close_items` for one `module` at a time (`prepayment`, `deferred_income`, `accrual`, `fixed_asset`). The list gives each schedule's period summary; `briefcase_get_close_item` gives its periods (set `period_start_date` and `period_end_date` for a long schedule) and the detail the user asks about, including the source transaction where there is one.
3. Cross-check with `briefcase_list_transactions` when the user suspects a prepayment was published as a straight expense.

Report amounts in the client's currency exactly as returned. Do not recompute schedules yourself; the tracker is authoritative.

## Draft changes

- `briefcase_create_close_item` creates drafts only. Accruals are created as a draft adjustment and are not posted. Always send a fresh `idempotency_key`.
- `briefcase_update_close_item` edits a draft or the future periods of a schedule. For an accrual it edits the adjustment amount, date and lines, not the recurring parent's estimate.
- Use `briefcase_get_reference_data` for balance sheet and expense accounts, and quote the account the schedule will post to.

## Publish, archive, restore

- Preview first: `mode: preview` on `briefcase_publish_close_item`, `briefcase_archive_close_item` or `briefcase_unarchive_close_item`. Summarise the journals that would post or reverse, the periods affected and any lock-date conflicts.
- Execute only after the user agrees, with the `preview_id`, `mode: execute` and a fresh `idempotency_key`.
- Publishing a schedule starts posting in Briefcase and the connected ledger; archiving reverses what was posted and stops future periods. Say this plainly before executing.
- Published fixed assets and committed accrual adjustments cannot be edited here; direct the user to the Briefcase app.

## Wrap up

Re-read the tracker after publishing so the user sees the updated position, and remind them the changes appear in the assistant activity under Settings → AI assistants. If the user is working towards closing the period, re-read the working paper so they see what is still outstanding.

View saved version →

---
name: ledger-reports
description: Read and explain a Briefcase Ledger client's profit and loss, balance sheet, trial balance, aged creditors and aged debtors, compare periods, and drill from a report line into the journals and source documents behind it. Use when the user asks how a client is doing, what makes up a balance, why a figure moved, who owes or is owed money, or for a trial balance or nominal balances.
---

# Ledger reports in Briefcase

These tools only work for Briefcase Ledger clients. Check `ledger_type` from `briefcase_list_clients` or `briefcase_get_client`; for a Xero or QuickBooks client they return `UNSUPPORTED_CAPABILITY`, so tell the user to read the reports in that ledger instead. Everything here needs the Ledger view permission; `FORBIDDEN` means the user lacks it.

## Pick the report

- **Profit and loss:** `briefcase_get_profit_and_loss` with `start_date` and `end_date`. Add `comparison_start_date` and `comparison_end_date` for "this month against last month" or "this year against last year". Filter with `business_id` or `property_id` only when the user asks about one business or property (`briefcase_get_reference_data` with `kind: businesses` or `properties`).
- **Balance sheet:** `briefcase_get_balance_sheet` with `as_at` (defaults to today) and optionally `comparison_as_at`. Retained earnings is the profit to date shown within equity, so `total_equity` equals `net_assets`.
- **Trial balance:** `briefcase_get_trial_balance` with `as_at` (defaults to today). Every account with a balance sits in a debit or credit column. Balance sheet accounts show the balance at `as_at`; revenue and expense accounts show the financial year to date, and earlier years' profit or loss is one `retained_earnings_brought_forward` line. `totals.difference` is `0.00` when the ledger balances. The financial year comes from the client's year end; if the tool says none is set, ask the user for the first day of the financial year and pass it as `financial_year_start`. Use it when the user asks for a trial balance or nominal balances, or to read control accounts such as VAT, debtors, creditors and clearing accounts in one call (`reserved_type` marks them).
- **Aged creditors or debtors:** `briefcase_get_aged_report` with `subledger: ACCOUNTS_PAYABLE` (creditors) or `ACCOUNTS_RECEIVABLE` (debtors) and `as_at`. Totals cover every contact; contacts come largest balance first, 25 per page with up to 10 invoices each. Page with `after` for more contacts, and set `contact_id` to see one contact's invoices in full.

Resolve relative periods ("last quarter", "year to date") to explicit dates, and say which dates you used. Ask for the financial year end when the user says "this year" and it matters.

## Report the numbers faithfully

- Amounts are decimal strings in the report's `currency`. Quote them as returned and follow the `sign_convention` in each result; do not recompute totals or re-sign figures.
- Accounts with no movement or a zero balance are left out, so an account missing from the list means it is nil for that range.
- Lead with the few lines that explain the answer (largest movements, biggest balances, oldest debts) rather than reading out every account.

## Drill down

1. Take the account `id` from a report line.
2. `briefcase_list_journals` with `account_id` and the same date range shows that account's activity; its `debit`, `credit` and `totals` cover that account only.
3. `briefcase_get_journal` for one entry shows every line and `source_links`, such as `sales_invoice_id` or `transaction_id`. Follow them with `briefcase_get_sales_invoice` or `briefcase_get_transaction`.

For an aged report line, the invoice `source` tells you which tool opens it (`SALES_INVOICE` → `briefcase_get_sales_invoice`, `TRANSACTION` → `briefcase_get_transaction`).

## Limits

These reports read Briefcase's own ledger. There is no VAT return tool; point the user to the Briefcase app for that. For bank reconciliation progress and which balance sheet accounts are signed off for a period, use `briefcase_get_working_paper` as described in the financial close review skill. For how-to questions about the reports, use `briefcase_search_help` rather than guessing.

View saved version →

---
name: management-accounts
description: Prepare monthly or quarterly management accounts for a Briefcase Ledger client as a draft for the accountant to review. Checks the books are ready, pulls profit and loss, balance sheet, trial balance, cash and aged debtors and creditors, works out KPIs, writes commentary on the movements that matter, and proves every figure against the ledger in a verification appendix. Use when the user asks for management accounts, a monthly or quarterly pack, a board pack, a month-end report, or how a client did this month or quarter.
---

# Management accounts in Briefcase

You prepare a **draft** management accounts pack that an accountant reviews before anything reaches their client. The pack is only useful if the accountant can trust it, so every figure comes from a Briefcase tool response, every check is shown, and every gap is declared rather than hidden.

Rules that apply throughout:

- **Figures come only from tool responses.** Never from memory, never estimated silently. Do arithmetic in code when the host can run code; otherwise show each calculation's inputs so the reviewer can repeat it.
- **Never post and never send.** Proposed adjustments (an accrual, a corporation tax estimate) go through the manual journals skill with a preview and the user's agreement. The pack goes to the accountant, not the client.
- **Mark the pack "Draft — for accountant review"** until the user confirms they have reviewed it.
- **Briefcase Ledger clients only.** Check `ledger_type` with `briefcase_get_client`. The report tools return `UNSUPPORTED_CAPABILITY` for Xero or QuickBooks clients; tell the user to use their ledger's own reporting and stop.
- The reports need the Ledger view permission. `FORBIDDEN` means the user lacks it; say so.

Work through the steps in order. Read the reference files when a step points to them.

## 1. Agree the brief

Settle these before pulling any figures. Use the defaults below and state them in the pack rather than stopping to ask; ask only when the client or period is unclear, or the financial year start cannot be found:

- **Client and period.** Month or quarter; resolve it to explicit `start_date` and `end_date` and say which dates you used.
- **Financial year.** `briefcase_get_trial_balance` reports the `financial_year_start` it used. If it says no financial year end is set, ask the user for the first day of the financial year.
- **Entity and accounting basis.** `briefcase_get_reference_data` with `kind: businesses` lists a sole trader's or landlord's businesses with their `type` and `accounting_method`. An empty list usually means a limited company on the accruals basis; confirm with the user when it matters. Cash basis businesses have no debtors, creditors or accruals to report, so leave those sections out and say why. Corporation tax applies to companies only.
- **Audience.** Owner (default), board, lender or investor. It changes emphasis, not the figures (see `references/pack-template.md`).
- **Comparisons.** Prior period and the same period last year by default. Budget comparison only when the user supplies a budget; never invent one.
- **Materiality.** A movement is material when it is at least 10% **and** at least £1,000 (or 1% of the period's revenue if larger). Tell the user the thresholds and use theirs if they give them.

## 2. Check the books are ready

Run the readiness checks in `references/verification.md` before pulling report figures:

- the working paper for the period end (what is left to clear, unreconciled accounts, accounts changed since sign-off);
- documents still awaiting review dated in or before the period;
- close schedules due but not posted;
- clearing and suspense accounts that are not nil;
- the lock date.

Do not stop here to ask whether to continue: the user asked for the pack. Carry on, put every failed check in the pack's caveats, and offer at the end to help fix them and rebuild. Never refuse to prepare the pack because the books are incomplete; make the incompleteness visible.

## 3. Pull the figures

Make these calls for the period end and keep each response; the verification appendix cites them.

1. `briefcase_get_profit_and_loss` for the period, with the prior period as the comparison.
2. `briefcase_get_profit_and_loss` for the period, with the same period last year as the comparison.
3. `briefcase_get_profit_and_loss` for the financial year to date, with the prior year to date as the comparison.
4. `briefcase_get_balance_sheet` at the period end, with the prior period end as `comparison_as_at`.
5. `briefcase_get_trial_balance` at the period end.
6. `briefcase_get_aged_report` at the period end for `ACCOUNTS_RECEIVABLE` and for `ACCOUNTS_PAYABLE` (accrual basis only).
7. `briefcase_get_reference_data` with `kind: accounts` for account `class`, `type`, `is_bank_account` and `reserved_type`.

Quote amounts as returned, in the response's `currency`, following each response's `sign_convention`. Accounts with no movement or a zero balance are left out of the reports, so a missing account is nil.

**Cost of sales.** Briefcase Ledger has no separate cost-of-sales account type. Treat expense accounts whose names describe direct costs (for example Cost of Goods Sold, Cost of Sales, Cost of Services, Purchases, Direct Costs, Subcontractors, Materials) as cost of sales, list the accounts you chose in the basis of preparation, and ask the user to confirm them the first time. If there are none, report revenue, overheads and net profit without a gross profit line rather than guessing.

## 4. Work out the KPIs

Pick 5 to 8 KPIs that suit the business and audience from `references/kpis.md`, compute them from the responses, and show each one's formula and inputs. Follow the pitfalls listed there, especially VAT in debtor days and the gearing definition.

## 5. Prove the figures

Run every tie-out in `references/verification.md`: balance sheet balances, P&L totals, year-to-date profit against retained earnings, trial balance totals, aged reports against control accounts, bank balances against the feed, KPI recalculation. Record each with the figures compared and pass or fail. A failure goes at the top of the pack with what you found; do not explain it away.

Then the analytical review in the same file: material movements, gross margin swings, regular costs missing this period (usually a missed accrual), balances on the wrong side, new accounts and large manual journals.

## 6. Find the reasons behind the movements

For each material movement (3 to 5 of them, largest first):

1. `briefcase_list_journals` with the account's `id` and the period's dates shows what posted.
2. `briefcase_get_journal` and its `source_links` lead to the documents (`briefcase_get_transaction`, `briefcase_get_sales_invoice`).
3. Write the cause only if the journals show it, and cite the journal or document. If they do not, turn it into a question for the client: "Rent is £2,000 above last month. Has the new lease started?"

## 7. Write the pack

Follow `references/pack-template.md`: a one-page summary first (what happened, why, and 3 to 5 suggested actions), then KPIs, profit and loss, balance sheet, cash, aged debtors and creditors, commentary, and the verification appendix with the basis of preparation.

Commentary says what happened, why, and what it means. Do not narrate numbers the tables already show, and do not make forward-looking claims the user has not given you. Report bad news as plainly as good news.

## 8. Check the draft before handing it over

Run the final checks in `references/verification.md`: fetch the period profit and loss, the balance sheet and the trial balance again with the same arguments as the first pull and compare their totals, and check every number and percentage in the text against the tables. If the books changed while you were working, say so and rebuild the affected sections.

## 9. Hand over

Give the user the pack marked "Draft — for accountant review", list the caveats and open questions for the client, and point them to the reviewer checklist at the end of the appendix. Offer to produce it as a document if the host can create files. Do not send it anywhere.

Referenced files: 3

View saved version →

---
name: manual-journals
description: Post a manual journal to a Briefcase Ledger client, such as a correction, reclassification, capital introduction or one-off period-end adjustment, with the accounts checked, the lock date respected and a preview agreed before anything posts. Use when the user asks to post, book or record a journal, move a balance between accounts, or correct a posting.
---

# Manual journals in Briefcase

A posted journal changes the client's accounts immediately and can only be reversed in the Briefcase app. Treat every journal as irreversible from here. Manual journals only exist for Briefcase Ledger clients (Xero and QuickBooks clients return `UNSUPPORTED_CAPABILITY`) and need the Ledger post permission.

## Before drafting

- Check whether a journal is the right tool. Recurring prepayments, accruals, deferred income and depreciation belong in the close tools (see the financial close review skill), and a miscoded bill should be fixed on the transaction, not journalled over.
- `briefcase_get_client` gives `general_ledger_lock_date`. Entries must be dated after it.
- `briefcase_get_reference_data` with `kind: accounts` for account ids (narrow with `account_class`, for example `EXPENSE`, or `search_term`), and `kind: tax_rates` when a line carries VAT. Quote each account's name and code back to the user.
- To correct something already posted, read it first with `briefcase_list_journals` (filter by `account_id` and dates) and `briefcase_get_journal`.

## Draft and preview

Call `briefcase_create_manual_journal` with `mode: preview`:

- `entry_date`, `description` and a `reference` the user will recognise later.
- `lines`: each has an `account_id` and either a `debit` or a `credit` (never both), as gross amounts in major units. A `tax_rate_id` splits the VAT to the VAT account automatically; revenue and expense lines need one.
- `business_id` (and `property_id` with it) when the entry belongs to one business or property.

Show the user the lines as a small debit and credit table with the totals, then explain any blocker:

- `PERIOD_LOCKED`: the date is on or before the lock date. Move the date or ask the user to move the lock date in the app.
- `UNBALANCED`: debits and credits differ. Never add a balancing line the user did not ask for.
- `RESERVED_ACCOUNT`: control accounts such as accounts receivable and payable cannot take manual journals; the fix belongs on the invoice or bill.
- Deleted or unknown accounts, invalid lines, and accounts spanning businesses or properties.

## Post

Only after the user explicitly approves the preview, call again with `mode: execute`, the `preview_id` and a fresh `idempotency_key`. Return the `web_url`, then show the effect: `briefcase_get_balance_sheet` or `briefcase_get_profit_and_loss` for the affected period.

If a call fails with a network error, retry with the same `idempotency_key`; Briefcase will not post the journal twice. Never retry with a new key to get round an error.

View saved version →

---
name: sales-invoicing
description: Raise sales invoices for a Briefcase Ledger client from its sales items, create customers without duplicating existing contacts, list outstanding invoices, fetch invoice PDFs and build a debtor chase list. Use when the user asks to invoice a customer, add a customer, see what is unpaid or overdue, or get a copy of an invoice.
---

# Sales invoicing in Briefcase

Sales invoices only exist for Briefcase Ledger clients; Xero and QuickBooks clients return `UNSUPPORTED_CAPABILITY`. Reading invoices needs the Ledger view permission, raising invoices and adding customers need Ledger post. `FORBIDDEN` means the user lacks one of them or an administrator has paused assistant changes; report it and stop.

## See what is outstanding

- `briefcase_list_sales_invoices` with `statuses` (`AWAITING_PAYMENT`, `PAID`, `WRITTEN_OFF`, `PROCESSING`) and `search_term` for a customer or reference. Page with the cursor.
- `briefcase_get_sales_invoice` for lines, VAT, outstanding balance, payments and emails sent. For the PDF, call `briefcase_get_attachment_download` with `pdf.attachment_id`; the link is short-lived, so hand it straight to the user and do not repeat it later.
- For a chase list, use `briefcase_get_aged_report` with `subledger: ACCOUNTS_RECEIVABLE`: group by customer, oldest bucket first, with each invoice's reference, due date and outstanding amount.

## Raise an invoice

1. Find the customer with `briefcase_list_contacts`. If they do not exist, see "Add a customer" below.
2. Find the items with `briefcase_get_reference_data` and `kind: items`. Each item has a fixed price and VAT rate; the invoice uses the item's current price. If nothing fits, the user must add the item in the Briefcase app.
3. Call `briefcase_raise_sales_invoice` with `mode: preview`: `customer_id`, `issue_date`, optional `supply_date` (defaults to the issue date), `due_date`, `bank_account_id` for the bank details to print, and `lines` of `item_id` and `quantity`.
4. Show the preview: customer, dates, each line's net and VAT, and the totals. Explain any blocker in plain language. `PERIOD_LOCKED` means the issue date is on or before the lock date; missing issuer address, VAT number or customer address must be fixed in the app first.
5. Only after the user agrees, call again with `mode: execute`, the `preview_id` and a fresh `idempotency_key`. Return the invoice reference and `web_url`.

Say before executing that the invoice posts to the ledger straight away, is not emailed to the customer, and can only be reversed in the Briefcase app.

## Add a customer

1. `briefcase_create_customer` with `mode: preview`, the `name`, and optionally `email` and `address` (`region_code` is the two-letter country code, for example `GB`).
2. If the preview lists `candidates`, show them and ask whether the user meant one of those. Use the existing contact if so.
3. `resulting_action: REUSE_EXISTING` means a contact with exactly that name already exists and will be made a customer rather than duplicated.
4. Execute with a fresh `idempotency_key`. Pass `confirm_new_despite_candidates: true` only when the user has confirmed the new customer is different from every candidate.

## Retries

Retry a failed call with the same `idempotency_key`; Briefcase returns the original result instead of raising a second invoice. For how-to questions, use `briefcase_search_help`.

View saved version →

---
name: transaction-review
description: Review bills and receipts awaiting review in Briefcase for a client, explain Autopilot decisions and review warnings, fix extracted values, and publish or archive with a preview first. Use when the user asks what needs review, why a transaction was coded a certain way, or wants to approve or clear a client's queue.
---

# Transaction review in Briefcase

Work as the signed-in Briefcase user on the clients they connected. Never guess a client: resolve the name with `briefcase_list_clients` first and confirm when two names are close.

## Find what needs attention

1. `briefcase_get_connection` once per session to confirm which clients are visible and whether changes are allowed.
2. `briefcase_list_transactions` with `awaiting_review: true` for the client. Page with the returned cursor; do not ask for everything at once.
3. For each item the user cares about, `briefcase_get_transaction`. Explain the extracted values, the Autopilot reasoning and every review warning in plain language before proposing an action.

## Fix values

- Use `briefcase_get_reference_data` for accounts (narrow with `account_class` or `search_term`), tax rates, tracking categories, businesses and properties before changing a coding. Quote the exact account name and code back to the user.
- `briefcase_update_transaction` saves edits as metadata; it is last-write-wins, so read the transaction again before editing when the user has been working in the app.
- Never change amounts, dates or suppliers without the user's confirmation. Say what you will change and wait.

## Publish or archive

- Always call `briefcase_publish_transaction` or `briefcase_archive_transaction` with `mode: preview` first. Summarise the preview: ledger, account, tax treatment, period, and anything that blocks it (missing supplier, locked period, permission).
- Only after the user agrees, call again with `mode: execute`, the `preview_id` from the preview and a fresh `idempotency_key` (a random string you generate once per action).
- If the call fails with a network error, retry with the same `idempotency_key`; Briefcase replays the original result rather than posting twice.
- `FORBIDDEN` means the user lacks that permission in Briefcase or an administrator has paused assistant changes. Report it; do not look for another route.

## Follow up

Use `briefcase_get_operation` to check an action that returned `dispatched`. Point the user to Settings → AI assistants → Activity for the record of everything you changed.