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. Addpreview: N(1 to 10) when the person asks to SEE proposals and refuses any change ("propose-moi 5 catégories, ne modifie rien"): the result then carriespreview, the first N rows with their label, amount, date andproposed_category, the category the categorize card would pre-fill, or null where no proposal is strong enough. It still draws nothing, so the proposals go in your text and nothing is written. A row with a nullproposed_categoryhas no proposal: say so, never invent one. With or withoutpreview, this kind carriescountandamountsfor the whole window, not the page: the count and the amount of the rows a read-only answer names in one line.unposted_transactions— a period's categorized rows still missing the ledger account they would post to. Needsfiscal_yearandfiscal_period. This kind also carriesunhydrated_ledger_defaults: signed rows whose counterparty already has a confirmed AP/AR default for the row's direction that Well is filling in the background. While that is above zero, re-read this probe and wait rather than assigning those rows by hand.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.gap_owners_to_invite— how many owners of the period's missing-invoice gaps are stillpendingornot_member, the people the invite step of a close or missing-invoice flow would offer. Name the period asperiodsor asfiscal_yearwithfiscal_period, or name none to use the months selected in this conversation, exactly aswell_list_member_candidates({ from_assigned_gaps: true })does. Ask it BEFORE that call, and make the call only when this answers above zero: an owner who already has access, such as a solo owner who assigned the gaps to themselves, is nobody to invite.
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. Four kinds are the exception and carry count. uncategorized_window totals the whole window in one aggregate beside its one-row read, so it also carries amounts: per currency, sum_negative and sum_positive with their counts, split by sign exactly as well_sum_transactions splits them (which side is money out is the feed's sign convention, elected from that sum's counts, never assumed), and unreadable_count, the rows in count whose amount does not read and sits in no sum. gap_owners_to_invite reads the same owner set the invite card reads, so the number is the card's own invitable rows. 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 workspace 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` and `gap_owners_to_invite` only: the calendar months to check, the same list the card takes. Every month must have ended. | |
| preview | No | `uncategorized_window` only: how many rows to return as `preview`, with the proposal the card would pre-fill. For a read-only ask that wants to see proposals; it draws nothing and writes nothing. | |
| worklist | Yes | Which repair gate to check. Each one names its own required scope in this tool's description. | |
| fiscal_year | No | `unposted_transactions` and `gap_owners_to_invite` 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` and `gap_owners_to_invite` 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. | |
| 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. | |
| counterparty_ids | No | `invoice_sources_for_pick` and `counterparties_to_categorize` only: the counterparties to check, copied from the `company_id` of the missing-invoices rows. It REPLACES the pick a card recorded in this session, so the gate answers for the companies named here and no others. Omit to check the whole scope. |
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 (`uncategorized_window`, `invoice_sources_for_pick`, `counterparties_to_categorize` where it equals the card's `uncategorized_count`, and `gap_owners_to_invite`); absent on the kinds answered one row at a time, and absent whenever `success` is false. | |
| error | No | ||
| amounts | No | `uncategorized_window` only: the rows in `count` per currency, split by the sign of the amount as `well_sum_transactions` splits them, each side a positive magnitude with its count. Which side is money out depends on the feed's sign convention: elect it from the window's `well_sum_transactions` counts, never assume it. Absent whenever `count` is absent. | |
| preview | No | `uncategorized_window` with `preview` only: the first rows of the window, in date order, each with the category the card would pre-fill or null. Absent whenever `success` is false. | |
| 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. | |
| 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. | |
| unreadable_count | No | `uncategorized_window` only: the rows in `count` whose amount does not read, so they sit in no entry of `amounts`. | |
| 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. | |
| unhydrated_ledger_defaults | No | `unposted_transactions` only: signed rows in the period whose counterparty already carries a confirmed AP/AR default for the row's direction but whose ledger account Well has not filled yet. Well hydrates these in the background; while it is above zero, wait and re-read this probe rather than assigning those rows by hand. Absent for other kinds and whenever `success` is false. |