Wait for selection
well_wait_for_selectionRead the user's card click, holding the turn open until it lands. Call it in the SAME turn, right after the tool whose card asks the user to click: well_list_workspaces (kind "workspace"), well_list_periods (kind "periods"), well_list_missing_invoices (kind "counterparties" — its card is the only one that records a counterparty pick), well_list_burn_exemptions (kind "exemptions"), well_list_recurring_contexts (kind "recurring_contexts"), well_list_cash_scope (kind "cash_scope"), well_list_connectors (kind "connect_ack" for the connect step, "bank_ack" for the bank step), well_list_counterparties (kind "categorize_ack" — its Continue and its Keep for later both write it), well_list_missing_invoice_owners (kind "assign_ack" — its Continue writes it), well_preview_invoice_fetch (kind "deploy_ack" — its Deploy, its Continue and its Keep for later all write it), well_show_company_candidates (kind "company_pick" — its Use this company mints the company workspace, switches into it and writes the ack in one call; its Keep for later writes the same ack with the outcome the click carried and moves no pin), well_show_retargetable_connectors (kind "retarget_ack" — its Confirm and its Keep for later both write it, with the outcome the click carried), well_list_member_candidates (kind "invite_ack" — its Send and its Keep for later both write it, with the outcome the click carried), well_get_ledger_export_status (kind "export_ack": its Confirm writes it), well_show_record_graph_summary (kind "record_graph_pick" — its Continue writes the confirmed record ids), or well_propose_next_steps (kind "next_step": a tile click writes it; on "selected", take selection.next_step.prompt as the user's own message and start that skill in the same turn, loading it with well_get_skill. Its continue tile also moves the pin to the person's own workspace, returned as selection.workspace_id: start the skill there). It waits up to 60s for the click. "selected" — continue the flow. "no_selection_yet" — call it again at once, at most 5 calls in this turn; after the fifth, end the turn on the card in one line, and the user's click then prefills the reply that resumes the flow.
status "selected": the choice is recorded.
selectioncarries it — the pinned workspace_id and workspace_queue (or, when the picker's Not now set the switch aside,outcome: "keep_for_later"with workspace_id null: nothing was picked, so resolve no workspace and stop the step), the picked periods, the picked counterparties (each { company_id, matched_connector_service_id } plus the workspace_id they belong to and theperiodsthey were listed for), the exempted category keys or the recurring context keys plus the workspace_id they belong to, or the acknowledgement plus the workspace_id it was made in and, on a card whose buttons say different things, theoutcomethe click carried.already_set: truemeans it was recorded since the card was drawn but before this call (the user had already clicked). Continue the flow with it.
Only a click recorded SINCE the card was drawn is reported. An answer left over from an earlier conversation stays in the session and is never handed back, so this tool always waits for the click the card in front of the user is asking for.
status "no_selection_yet": nothing has been recorded since the card was drawn and no click landed within the wait (default 60s, clamped 5-60s). This is a NORMAL result, not an error. Call this tool again at once, up to 5 calls in one turn. After the fifth, end the turn on the card in one line; the user's click then prefills the reply that resumes the flow.
A counterparty pick belongs to the workspace AND the months it was made against, and it carries those months in selection.periods. A switch to another workspace, a change of the selected months, or a fresh well_list_missing_invoices card drops it. So kind "counterparties" never hands back a pick made against another month: with that pick dropped, the call waits for the new click instead. A pick recorded BEFORE this call is reported only when it was made in the workspace this call targets, so pass workspace_id to ask about a workspace the conversation is not switched to. A pick that lands DURING the wait rides back with the workspace it was made in. Compare selection.workspace_id before you act on it.
A burn-exemption answer belongs to the workspace it was made in and rides back as selection.workspace_id, and it carries no months: a category is or is not burn for the business, so the same answer holds over any window. An EMPTY selection.exempt_categories on status "selected" means the user exempted NOTHING — act on it, do not re-ask. A switch to another workspace drops it; a change of the selected months does not.
A recurring-contexts answer follows the same rules as a burn-exemption answer: it belongs to the workspace it was made in, carries no months, and an EMPTY selection.recurring_contexts on status "selected" means the user counts NOTHING as recurring — act on it, do not re-ask.
A cash-scope answer follows those same rules, and its empty case is the one to read carefully: an EMPTY selection.counted_account_types on status "selected" means the user counts NOTHING as cash. That is a resolution, not a scope of size zero — say there is no cash position left to report and END the run, rather than carrying an empty scope into a total the renderer cannot draw.
Kind "cash_scope" is the reader's ANSWER — the account types they ticked, and nothing else. It is not well_render_cash_forecast's cash_scope field, which is the fuller policy an answer feeds into (the counted types plus the ownership and exclusion counts the caller measured).
An acknowledgement belongs to the workspace it was made in, and rides back as selection.workspace_id. On kinds "categorize_ack", "deploy_ack", "retarget_ack", "company_pick", "demo_handoff" and "invite_ack" it also carries selection.outcome: "done" means the user carried the step out, "keep_for_later" means they set it aside. Both end the step, so continue the flow either way and say in half a sentence which one it was. "export_ack" carries no outcome: its card confirms and nothing else. A switch to another workspace drops it. An ack recorded BEFORE this call is reported only when it was made in the workspace this call targets, so pass workspace_id to ask about a workspace the conversation is not switched to. A click that lands DURING the wait is reported with its own workspace, which can be another card's. Compare selection.workspace_id before you act on it.
A record-graph selection belongs to the workspace it was confirmed in and rides back as selection.workspace_id, plus selection.record_graph ({ workspace_id, root, records: [{ id, label }] }). It carries no months. A switch to another workspace drops it. A pick recorded BEFORE this call is reported only when it was made in the workspace this call targets, so pass workspace_id to ask about a workspace the connection is not switched to.
This tool reads and waits — it changes nothing.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | Which card click to wait for: "workspace" (the workspace picker's Use or Not now), "periods" (the month picker's Validate), "counterparties" (the missing-invoices card's Continue), "exemptions" (the burn-exemption card's Continue), "recurring_contexts" (the recurring-contexts card's Continue), "cash_scope" (the cash-scope card's Continue), "accounting_settings_ack" (the accounting-settings card's Confirm), "connect_ack" / "bank_ack" (the connect card's Continue), "categorize_ack" (the categorize card's Continue or Keep for later), "assign_ack" (the owner-assignment card's Continue), "deploy_ack" (the collect-agents card's Deploy, Continue or Keep for later), "company_pick" (the company-candidates card's Use this company or Keep for later), "invite_ack" (the invite-members card's Send or Keep for later), "retarget_ack" (the connector-retarget card's Confirm or Keep for later), "export_ack" (the ledger-export card's Confirm), "record_graph_pick" (the record-graph-summary card's Continue), "demo_handoff" (the next-steps card's continue tile, which also answers "next_step"), "next_step" (a tile click on the next-steps card). | |
| timeout_s | No | How long to wait, in seconds. Default 60, clamped to 5-60. | |
| workspace_id | No | Target 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. | |
| waiting_notice | No | One short line the person reads while this call holds the turn open, IN THE LANGUAGE THEY ARE WRITING IN. Say what you are waiting for them to do on the card, in your own words, not what the server is doing: they are the one holding the flow. Omitted falls back to an English line, which a reader working in another language may not read, so write it whenever you know their language. | |
| 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 |
|---|---|---|---|
| hint | No | ||
| kind | No | ||
| error | No | ||
| status | No | ||
| success | Yes | ||
| selection | No | The value the click wrote. Present only when status is "selected". | |
| already_set | No | True when the click had already been recorded since the card was drawn, before this call started — no wait happened. | |
| 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. |