List uncategorized transactions in a window
well_list_uncategorized_windowList the transactions in a date window that carry no category, so a figure that depends on categorization can say exactly what is missing before it is computed.
from is inclusive and to is EXCLUSIVE — for whole months, pass the first day of the month after the last one you want.
These rows are measured on when the movement happened (executed_at), not on its accounting date. That is deliberate and it matters: the two disagree about which MONTH a transaction belongs to for a large share of real data, and many rows carry no accounting date at all. A caller listing rows on one basis while summing a figure on the other ends up with rows it counts but cannot offer to fix. Pair this with a sum measured on the same basis.
Returns each row's identity, amount, counterparty and the classifier's pending suggestion where one exists. It lists rows with NO category; a categorized row that has not yet posted to the ledger is a booking question and is not returned here.
exclude_transaction_ids drops rows the user already parked in this conversation (skipped, or sent to the web picker). Pass the ids a categorization hand-back names, so the next batch moves on instead of serving them again. The rows stay uncategorized; only this read leaves them out.
meta.truncated: true means the page filled and more rows exist. meta.returned is what came back. totals covers the whole window, not the page: count, the amounts per currency split by sign into sum_negative / count_negative and sum_positive / count_positive exactly as well_sum_transactions splits them, and unreadable_count. Both sums are positive magnitudes. Which side is money out is a property of the FEED, not of this read: elect it from the window's well_sum_transactions counts before you call either side spend or income. On a feed that stores magnitudes only, every row sits in sum_positive and this read cannot tell money out from money in, so state the count and the amount without a direction. State the total from totals; when totals is null and the page is truncated, report the count as a floor.
success: false means the window is UNKNOWN, not empty. The read failed, so no count exists and returned and truncated are absent rather than zero. An empty records on a failed read is not "nothing is uncategorized" — treating it that way reports a clean list this read never produced. Say the list could not be read.
Do not propose categories from this list. Where the classifier has a proposal it rides on the row, and the assignment surface is where a category is chosen.
When the user asks to see, list or fix these rows, call this tool directly: its card is the answer. ⚠️ This tool draws its card on EVERY call, the empty one included. So when nobody asked for the list and you only need to CHECK whether anything is left (the first pass of a gate, or a re-check after a repair), call well_get_worklist_status({ worklist: "uncategorized_window", from, to }) first, with the same scope you would pass here. It draws nothing. Call this tool after it only when it answers open: true.
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 |
|---|---|---|---|
| to | Yes | EXCLUSIVE end of the window, YYYY-MM-DD. | |
| from | Yes | Inclusive start of the window, YYYY-MM-DD. | |
| limit | No | Max rows to return (default 500). | |
| 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. | |
| 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. | |
| exclude_transaction_ids | No | Transaction ids to leave out: the rows parked in this conversation. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | ||
| totals | No | ||
| window | Yes | ||
| records | Yes | ||
| success | Yes | ||
| returned | No | ||
| truncated | 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. | |
| category_audience | No | ||
| offeredCategories | No | ||
| 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. |