Get worklist status
well_get_worklist_statusAsk whether a repair gate is still OPEN, without drawing its card.
Call this BEFORE the worklist read whenever you are checking rather than repairing — the first pass of a gate, and every re-check after the reader has cleared one. open: false means the gate is settled: carry on, and call nothing else.
Only call the worklist read when this says open: true. Those reads draw a card on every call, empty included, so reaching for one to find out whether there is anything to do puts a picker with no rows and a dead button in front of the reader. The tool that draws each card comes back as card_tool.
WORKLISTS, and the scope each one needs:
accounts_needing_company— the accounts with no company attached, or whose ownership is still unknown. No scope.uncategorized_window— the transactions in a window carrying no category. Needsfrom(inclusive) andto(EXCLUSIVE), bothYYYY-MM-DD.unposted_transactions— a period's categorized rows still missing the ledger account they would post to. Needsfiscal_yearandfiscal_period.invoice_sources_for_pick— how many of the vendors the user picked on the missing-invoices card carry a connector that can bring an invoice in. No scope: the pick is on this session's own lane. Ask it BEFORE anywell_list_connectors({ from_selection: true })call, and make that call only when this answers above zero — a pick with no invoice source behind it draws a picker with no rows and a dead button.counterparties_to_categorize— the counterparties whose invoices the named months are still missing and that carry no industry category. Needsperiods, the same[{ calendar_year, calendar_month }]list the card takes.
A scope field the named worklist needs is REQUIRED. Omit one and this refuses: a gate reported clear over the wrong window cannot be told from one that is genuinely clear, and the figure behind it would be computed on that.
success: false means the gate is UNKNOWN, not clear. open is ABSENT on that path, so a failed read can never be mistaken for a settled worklist. Retry once; on a second failure say the gate could not be read and stop, rather than computing a figure on evidence you never obtained.
Most worklists report no COUNT. One row answers "is it open", and the count of what is left comes from the worklist read itself — which you are about to call anyway when the gate is open. Two kinds are the exception and carry count. invoice_sources_for_pick reads its whole set by id in one go, never paged, so the number comes free. counterparties_to_categorize reads the whole month population rather than one row, so the number is already in hand, and it is the same number the card reports as uncategorized_count.
COST: counterparties_to_categorize reads each named month's spend — the same reads its card makes, and a scope with work left in it pays for them TWICE, once here and once when the card draws. A clean scope pays once and skips the card entirely, which is what the check buys. Probe the months the user actually named, not a whole year "to be safe".
When the token authorizes one workspace, call this directly — no other tool call is needed first. When it authorizes several, this read will not guess which one you mean: pass workspace_id on the call.
That holds for every gate but two. invoice_sources_for_pick and counterparties_to_categorize follow their cards instead: well_list_connectors and well_list_counterparties both answer from the token's primary workspace when you name none, so those gates answer from the same one. A probe that refused where its card answers would be describing a different workspace from the card it stands in for. The result names the workspace that answered.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | `uncategorized_window` only: the day AFTER the window's last, exclusive. | |
| from | No | `uncategorized_window` only: the window's first day, inclusive. | |
| periods | No | `counterparties_to_categorize` only: the calendar months to check, the same list the card takes. Every month must have ended. | |
| worklist | Yes | Which repair gate to check. Each one names its own required scope in this tool's description. | |
| fiscal_year | No | `unposted_transactions` only: the period's fiscal year. | |
| 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 | No | `unposted_transactions` only: 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. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| open | No | Whether the worklist still holds a row. Absent when `success` is false — an unknown gate, not a clear one. | |
| count | No | How many rows the gate still holds. Carried only by the kinds whose read counts the whole set (`invoice_sources_for_pick`, and `counterparties_to_categorize` where it equals the card's `uncategorized_count`); absent on the kinds answered one row at a time, and absent whenever `success` is false. | |
| error | No | ||
| success | Yes | ||
| worklist | Yes | The gate that was checked, echoed back. | |
| card_tool | Yes | The tool that draws this worklist's repair card. Call it only when `open` is true. | |
| 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. | |
| 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. |