Skip to main content
Glama

List periods

well_list_periods
Read-only

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 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_invoices would 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". 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.

  • 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, like days is 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

TableJSON Schema
NameRequiredDescriptionDefault
yearNoOne 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`.
titleNoHeading for the picker card shown to the user. At most 120 characters.
monthsNoHow 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.
purposeNoWhy 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.
subtitleNoSupporting line under the picker card's heading. At most 240 characters.
workspace_idNoTarget 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

TableJSON Schema
NameRequiredDescriptionDefault
errorNo
hintsNo
periodsYes
successYes
workspace_idYes
base_currencyYes
default_periodYes
navigable_yearsYesThe calendar years a `year` request is answered for. A picker's year steppers stop here.
resolved_workspaceNoThe workspace that answered, when the caller named none and the token authorizes several.
fiscal_year_start_monthYes

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already mark it read-only and non-destructive, and the description adds substantial behavioral context: the subtle 'selectable' vs 'inspectable' distinction, 'invoice_state: none' explicitly never meaning 'nothing missing', the cost model of one extra read per active month, and the null default_period behavior. No statement contradicts the readOnlyHint.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose, uses clear section headers (PURPOSE, WINDOW, COST), and almost every caveat earns its place given the tool's semantic traps. It is long, and some field-by-field explanations could be deferred to the output schema, so it is not maximally concise for a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with six optional parameters, many sibling month-scoped tools, and subtle return-field semantics, the description covers selection intent, edge cases (future years, empty months, disconnected connectors), cost behavior, and defaults. Nothing an agent needs to call it correctly appears to be missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although schema coverage is 100%, the description adds meaning beyond the schema: purpose must be set by the calling skill and never inferred from wording, year returns a full calendar year and future months are included but unselectable, months has a cost implication, and workspace_id falls back to the token's primary workspace. These are operational details the schema alone does not convey.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'List the recent accounting months of the workspace' with close status, invoice-retrieval state, and work counts. It immediately states the tool's role ('Use this to ask the user WHICH month or months to work on before any close, review, or month-scoped read'), which sets it apart from siblings like well_list_missing_invoices that operate on an already chosen month.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly says when to call it ('before any close, review, or month-scoped read'), what not to do ('do not guess a month, and do not derive one from today's date yourself'), and that no prerequisite call is needed. The PURPOSE section also tells the agent whether to pass 'close' or omit it based on the flow's intent, which is actionable selection guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.5/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: CRUD for companies, people, and invoices; financial analytics (cash, cost, runway, holdings); connector management and invocation; schema discovery; querying; reconciliation; and contact channel management. No two tools could be confused for the same action.

Naming Consistency5/5

All tools follow the `well_verb_noun` pattern with consistent verb choices (create, get, list, update, delete, add, remove, run, resolve, query, invoke). The naming is predictable and makes the tool's purpose immediately clear.

Tool Count4/5

With 26 tools, the set is slightly above the ideal 3-15 range, but every tool earns its place given the breadth of the domain (CRM, invoicing, financial analytics, reconciliation, connector management). The count is well-scoped and not excessive.

Completeness4/5

The tool surface covers core CRUD, financial KPIs, reconciliation, and connector management. Minor gaps exist (e.g., no direct tool to update contact channels or manage accounts), but the query and schema tools allow agents to work around them, and the primary workflows are fully supported.

Resources