List transactions still to post
well_list_unposted_transactionsList the transactions of a fiscal period that carry a category or a role and have STILL not reached the ledger, so a close can say exactly what is holding it.
This is the posting gap, not the categorization gap. A row here already has a category; what it lacks is the ledger account its journal entry would post to. For rows carrying no category at all, use well_list_uncategorized_window.
Each row carries transaction_id, label, amount, period_date, the current_ledger already attached where one is, and ledger_suggestions — the classifier's proposals, each with the account's code (its number, e.g. "6156") beside its name.
The ledger_catalog.accounts list carries every account this workspace can post to, with the id well_set_transaction_ledger_account takes. A row whose ledger_suggestions is empty is assigned from that list: the classifier proposed nothing, which is not the same as the row having nowhere to go.
The rows arrive snake_cased (period_date, ledger_suggestions, current_ledger), unlike well_list_uncategorized_window, whose close cousin emits camelCase. A caller reading one shape against the other silently sees empty fields rather than an error.
The period is named in FISCAL terms, and a workspace's fiscal calendar need not follow the calendar year: "June 2026" is not reliably fiscal period 6. Take fiscal_year and fiscal_period from a well_list_periods entry, or from the months the user already selected in this conversation; never derive them from a calendar month yourself.
Most categories already determine their ledger account: the chart maps each category key to a canonical code, and only a handful abstain because the category alone cannot pick a safe account without the transaction direction. So a long list here usually means the categories are missing, not the accounts.
success: false means the period is UNKNOWN, not clear. The read failed, so no count exists, and an empty records on a failed read is not "everything posted".
truncated: true means the period holds MORE unposted rows than this page carries, so returned is a floor rather than the period's total. Narrow the period, or state the count as "at least".
When the user asks to see, list or fix the transactions still to post, call this tool directly: its card is the answer. ⚠️ This card draws ONLY when a transaction still needs a ledger account. A fully-read page whose transactions all already have one draws NOTHING (an empty/cleared period, and a truncated page whose shown rows are all assigned, still draw) — those rows are held by something other than the ledger, so do not announce a card the reader cannot see. When nobody asked for the list, or you only need to CHECK the gate (the first pass, or a re-check after a repair, or waiting out background hydration), call well_get_worklist_status({ worklist: "unposted_transactions", fiscal_year, fiscal_period }) first: it draws nothing and reports unhydrated_ledger_defaults (rows Well is still filling on its own — wait, do not draw yet) and open. Call this tool after it only once hydration is zero AND a row still needs an account.
When the token authorizes one workspace, call this directly — no workspace call is needed first. When it authorizes several, this read will not guess which one you mean: pass workspace_id on the call.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max rows to return. | |
| fiscal_year | Yes | The fiscal year of the period to read. | |
| workspace_id | No | Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several: this read reports one workspace's own figures and will not choose which. | |
| fiscal_period | Yes | The fiscal period, 1-12 for a month; 13 is the adjustment period and resolves to no rows. | |
| conversation_id | No | The conversation id returned by the previous Well result, in its meta under well/conversation_id, in its structuredContent, or in its JSON text block. Pass it back on every call in the same conversation, including a call a card makes, so the chosen workspace and the earlier answers still apply. It decides the conversation on its own: nothing the host states about the session replaces it. Omit it only on the first call of a conversation. | |
| workspace_scope | No | Restrict this call to the family: the token's primary workspace plus the company workspaces under it that you are a member of. Unrelated authorized workspaces drop out of the read; row reads merge across the family, while a per-workspace figure still reports exactly one workspace. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | ||
| records | Yes | ||
| success | Yes | ||
| returned | No | ||
| truncated | No | ||
| ledger_catalog | No | ||
| conversation_id | No | The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation. | |
| newly_connected | No | Tools that connected to this workspace since the last result and that no session was told about yet, oldest first. Present only when at least one tool is new. The connected-line rule says when to tell an entry; when it does, one line per entry, in the person's language: "<name> is connected.". Never fold several entries into one sentence. Each entry comes back once, on one result only: never repeat its line later. | |
| resolved_workspace | No | The workspace that answered, when the caller named none and the token authorizes several. | |
| conversation_id_note | No | Present only when the server opened a fresh lane, stating that no choice recorded earlier was read. | |
| conversation_id_source | No | Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened. |