Optional tool groups #
Fifteen tools ship enabled. Fifteen more sit behind three environment flags, all off by default.
A group that is off is invisible. It does not appear in the server’s tool list at all, so the assistant cannot discover it, ask you to enable it, or route around its absence. Deciding what to switch on is yours alone — which is why this page exists.
Two reasons for the default. Every enabled tool’s schema travels in the model’s context on every request, so the default surface is the ledger work an assistant actually does. And these are the only tools that delete a real resource rather than a draft.
| Flag | Tools | Enable it when |
|---|---|---|
MICROBOOKS_PERIOD_CLOSE | 3 | You want the assistant to help close a reporting period |
MICROBOOKS_RECYCLE_BIN | 2 | You want it to undo soft deletes, or clear them out |
MICROBOOKS_SETUP_TOOLS | 10 | You want it to build or maintain the chart of accounts |
Period close — MICROBOOKS_PERIOD_CLOSE
#
| Tool | What it does |
|---|---|
prepare_period_close | Step 1. Drafts the closing transactions. Requires the period to be in ADJUSTING, and an EQUITY account to post translation differences to |
review_period_close | Step 2. Lists what the close would commit, with the currencies and closing rates. Read-only, safe to repeat |
post_period_close | Step 3. Commits it. Irreversible, and always asks you to confirm |
Three tools rather than one, deliberately. A close is gated by the period’s status, drafts transactions a person should look at, and only then commits them permanently — the seam between proposing and committing is exactly where someone should be watching, so the tool surface keeps it open.
The forex account must be of typeEQUITY. Any other type is rejected withdetail_code103, and a multi-currency entity also needs a closing rate for each foreign currency before a period will close.
Moving a period into ADJUSTING is a separate, explicit act via
manage_reporting_period, so enabling this group also enables that tool.
Recycle bin — MICROBOOKS_RECYCLE_BIN
#
| Tool | What it does |
|---|---|
manage_recycled | List what is in the bin, inspect an entry, or restore it |
destroy_recycled | Delete a recycled resource permanently |
Anything deleted through the server — a discarded draft, a removed account
or tax — lands here rather than disappearing, so manage_recycled is the
undo button for the whole surface.
destroy_recycled is the one operation a typo cannot survive, so it is
guarded twice. It has no dry run; it always asks you to confirm; and it
requires you to spell out what the entry holds, in the form Tax 7, which
the server checks against the entry before doing anything.
A bin entry’s id is not the id of the resource inside it. Entry3can holdTax 7. The tools take the entry id, andmanage_recycled’s listing shows both.
Setup — MICROBOOKS_SETUP_TOOLS
#
Ten manage_* tools, one per resource, each taking a create / update /
delete action: manage_account, manage_category, manage_tax,
manage_discount, manage_currency, manage_exchange_rate,
manage_closing_rate, manage_reporting_period, manage_opening_balance
and manage_entity.
Every create and update is read back and compared field by field, so a value the API did not store is reported rather than assumed. Deletes are soft and recoverable from the recycle bin.
manage_entitydeletes a whole set of books, not one record — every account, transaction and report inside it. Enable this group only when you actually want the assistant maintaining your setup, and consider pairing it withMICROBOOKS_CONFIRM_POST.
Turning them on #
Flags go in the same env block as your token; any of 1, true, yes or
on enables one. See Configuration for a
worked example.