List periods
well_list_periodsList the recent accounting months of the workspace, with each month's close status, its invoice-retrieval state, and the counts that describe how much work it holds. Use this to ask the user WHICH month or months to work on before any close, review, or month-scoped read — do not guess a month, and do not derive one from today's date yourself.
Each entry carries:
calendar_year / calendar_month: the month itself.
fiscal_year / fiscal_period: the same month in the workspace's fiscal calendar — this is the pair every close endpoint and close tool takes.
label: the month written out, e.g. "March 2026".
is_complete: the calendar month has ended. A still-accruing month is never a valid close target.
selectable: the month can be CLOSED. False for a month that has not ended, one already closed, one with nothing to close, and a December whose year-end close is not supported yet. Read this one for a close pick.
inspectable: the month can be LOOKED INTO. A reader can open its transactions, its missing invoices and its days. True for EVERY month that has begun, the month in progress included. False only for a month that has not begun. It reads no close verdict and no activity count, so a closed month, an empty month and a workspace with no accounting connector at all still have readable months. An empty month answers with an empty list, which is an answer. Read this one for a retrieval or review pick; every selectable month is also inspectable.
close_status: "closeable" (ready), "not_ready" (work remains), "closed" (already locked), "nothing_to_close" (no activity), or null when the workspace has no verdict for that month.
close_reason: the blocking reason behind the status, or null.
invoice_state: "missing_invoices" (at least one counterparty still owes a supplier invoice), "has_invoices" (checked, and nothing is missing), or "none" (no state: no activity, the month has not begun, or the check could not run). Never read "none" as "nothing missing".
missing_invoice_count: how many counterparties owe an invoice for the month — the rows
well_list_missing_invoiceswould return. 0 whenever invoice_state is "none", including when the check did not run.transaction_count: how many transactions the month holds, whatever delivered them.
bank_transaction_count: the subset of transaction_count delivered by a connector the workspace actually BANKS with, meaning a bank, a neobank, or a treasury or spend platform whose product is an account. An accounting platform and a payment processor deliver transactions too, so transaction_count is NOT a bank signal. Only this field answers "has a bank fed this month". A transaction counts as not-bank when its source connector is unknown, or when that connector has since been disconnected, so a zero here never licenses skipping a bank-connection step.
unposted_invoice_count: invoices the month HAS that have not posted to the ledger. This is a posting gap, not a missing invoice — do not present it as one.
uncategorized_transactions: transactions in the month not yet categorized — the "help categorize" errand behind a not-ready close.
categorized_unposted_transactions: categorized transactions not yet posted to the ledger — part of the "review and book" errand.
days: the DAYS of the month that carry a retrieval state, ascending, each
{ day, state }over the same vocabulary as invoice_state. A day is "missing_invoices" when it holds settled expense spend still missing its supplier invoice, and "has_invoices" when it holds activity and no such gap. Days with neither are OMITTED, so an absent day means "none".daysis empty for every month whose invoice_state is "none" — an unchecked month has no day the tool can call clean. This is calendar detail for a picker to paint; quote the month's own counts, not a day list, when answering in prose.close_days: present ONLY for a
purpose: "close"call — the DAYS carrying a non-neutral close-readiness state, ascending, each{ day, state }over "posted" / "progress". A day absent from it is "neutral" (nothing to close). Calendar detail for the close picker, likedaysis for retrieval.
default_period is the oldest month that is ready to close, falling back to the oldest still in progress. Offer it as the default choice. It reads selectable, so it is null whenever no month in the window can be CLOSED, and a null one does not mean the window is empty: an inspectable month can still be worked on for invoice retrieval.
PURPOSE: pass purpose: "close" when the user is closing the books, so the picker paints close readiness and each month carries its close_days and the categorize / review counts. Omit it (or purpose: "collect") for invoice retrieval, the default. This is the calling skill's intent — set it from the flow, never from the user's phrasing.
WINDOW: by default the months most recent calendar months, ending with the current one. Pass year instead to get ONE calendar year in full — all twelve of its months, December back to January — which is how you reach a year the recent window does not cover, backwards or forwards. navigable_years reports the range year is answered for.
A year ahead of today comes back in full and every month of it is selectable: false and inspectable: false with close_reason "period_not_ended": books close on a month that has ENDED, and a month that has not begun holds nothing to read. Show such months when the user asks to look ahead, and say why they cannot be picked. Never omit them.
COST: the invoice state is read per month from a separate endpoint, so a wide window costs one extra read for every month that holds activity, plus one day-coverage read per calendar year those months touch. Ask for the months the user needs, not 24 by default. A wholly future or wholly empty year is cheap — no month in it can hold a settled gap, so none is read.
Call this directly — no other tool call is needed first (the workspace is resolved from the caller's authorized token, same as every other well_* tool).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| year | No | One calendar year to return in full — all twelve of its months, December back to January, instead of the recent window. Use it to reach a year the recent window does not cover, in either direction; future months come back visible but never selectable. Accepted range: 2000-2100, also reported as `navigable_years`. | |
| title | No | Heading for the picker card shown to the user. At most 120 characters. | |
| months | No | How many recent calendar months to return, ending with the current month. Each month holding activity costs one extra read for its invoice state. Ignored when `year` is given. | |
| purpose | No | Why the months are being listed, set by the calling skill (not guessed from the user's words). "close" is book closure: the card paints close readiness, and each month carries its per-day `close_days` and the counts behind its "why not ready" errands. Omit or "collect" for invoice retrieval (the default), which paints the retrieval axis and skips the close-readiness fields. | |
| subtitle | No | Supporting line under the picker card's heading. At most 240 characters. | |
| workspace_id | No | Target workspace. This read reports one workspace's own data. Omit it and the token's primary workspace answers, which may not be the one you mean; the result names the workspace that did. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | ||
| hints | No | ||
| periods | Yes | ||
| success | Yes | ||
| workspace_id | Yes | ||
| base_currency | Yes | ||
| default_period | Yes | ||
| navigable_years | Yes | The calendar years a `year` request is answered for. A picker's year steppers stop here. | |
| resolved_workspace | No | The workspace that answered, when the caller named none and the token authorizes several. | |
| fiscal_year_start_month | Yes |