Show the workspace picker
well_show_workspace_pickerAsk the user WHICH workspace to work in, on a card: one tile per authorized workspace, with its logo and the company behind it.
⚠️ ONLY when the token authorizes SEVERAL workspaces and no hint resolves to one. Every other case is yours to settle with well_list_workspaces, which draws nothing: exactly one workspace in the grant, a name or company the user already named, a pin this conversation itself wrote, or no workspace at all. A chooser over a set of one asks nothing, and a chooser you could have answered yourself asks the reader a question you already know the answer to. One narrow exception: a define-workspace run that requires a company workspace draws this card over the single company workspace under a membership, scoped with workspace_ids, so the person consents before the move; its Not now resolves unresolved and moves nothing.
⚠️ WAIT ON THE CARD IN THE TURN THAT DREW IT. Write your one line for the user FIRST — the wait holds the turn open for up to a minute, and a user looking at a card with no sentence beside it has been given no reason to click — then call well_wait_for_selection({ kind: "workspace" }), which this result's next_step also states. The click writes the pin server-side, so never follow it with well_switch_workspace.
⚠️ NEVER DEFAULT TO THE PRIMARY WORKSPACE on the user's behalf, and do not restate the workspaces in text under the card.
⚠️ WRITE reply IN THE USER'S LANGUAGE, WITH {picked} WHERE THE WORKSPACE NAME BELONGS. A click sends that sentence into the conversation as the person's own message, and the card puts the workspace they actually picked in place of the placeholder. A sentence left unwritten sends English to a reader who is not writing in English; a sentence that names a workspace itself is refused, because you are writing it before they have chosen.
The rows are the rows of well_list_workspaces, field for field. Its description carries the field reference, and this description does not repeat it.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| reply | No | One sentence, IN THE LANGUAGE THE USER IS WRITING IN, that the click sends into the conversation as their own message. Write what the PERSON would say about the workspace they pick, in their words, not an instruction to yourself. You write it BEFORE they click, so you cannot know what they will choose: put {picked} where the pick belongs and the card replaces it with the names they actually picked, one or several. In English it would read "Let's work on {picked}." Write the same shape in the user's language. {picked} is required: a sentence that names a pick itself names the one you guessed, so the card refuses it and sends its own English instead. At most 160 characters. Omitted sends an English sentence the card builds itself, which is wrong for any reader not writing in English. | |
| title | No | Heading for the picker card, framing the step in its flow (e.g. "Which company are we closing?"). At most 120 characters. Omit to keep the default wording; an empty string is rejected rather than rendered as a blank heading. | |
| subtitle | No | Supporting line under the picker card's heading. At most 240 characters. Omit to keep the default wording; an empty string is rejected rather than rendered blank. | |
| workspace_id | No | Target workspace. Optional: this tool describes the token itself rather than one workspace's data, so omitting it returns the same answer. | |
| workspace_ids | No | Scope the tiles to this subset of the authorized workspaces, e.g. the company workspaces under one membership. Every id must be one this token authorizes; an id outside the grant refuses the call. Omit to draw every authorized workspace. | |
| 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 | ||
| session | No | What this conversation's card clicks recorded so far; null/empty fields when nothing was clicked yet. | |
| success | Yes | ||
| next_step | No | What to do with the card this result renders. Added by the dispatcher when the card asks for a click. | |
| workspaces | Yes | ||
| field_legend | 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. | |
| conversation_id_note | No | Present only when the server opened a fresh lane, stating that no choice recorded earlier was read. | |
| default_workspace_id | Yes | The tile the picker card preselects on a brand-new account: the demo workspace, when the grant holds exactly one demo and every other workspace is still empty (no company of its own, no registered name, currency or fiscal year, no connected source, no business data) and this conversation has not pinned another workspace. Null otherwise, and on a scoped picker. It chooses nothing: nothing acts on it without the person's click. Not the same as is_primary. | |
| 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. |