well_list_periods

io.github.WellApp-ai/well-mcp · Verify this server

List 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 user can actually start work on this month. 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. - 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 ended, 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_invoices` would return. 0 whenever invoice_state is "none", including when the check did not run. - transaction_count: how many transactions the month holds. - 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. - 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". `days` is 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. `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 is null when no month in the window can be worked on. 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. 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).