Propose next steps
well_propose_next_stepsPut five next steps on a card, as five tiles the person can click.
This tool ranks nothing. The five skills and their order come from well_get_session_digest's suggested_steps; pass them in that order. The server adds at most one tile of its own, described below. The sentence for each one is yours to write, in the language the person is using, from that skill's own quoted utterances and the figures the digest returned. The tile shows only the skill's catalog title and promise: your sentence is not on the card, and a click sends it as the person's own message. Put the figure in the sentence, and do not count on the card to show it. The one exception is first_session: true, which only the welcome of a person's first session passes: each tile then shows your sentence as its title, so every sentence there is a short job of 8 words or fewer. When that list is empty or shorter than five, do NOT call this tool and do not write five of your own: say in one line that the next steps cannot be proposed this time. The server checks that each line can travel and hands the list to the card. Call it at the END of a skill that tells you to, never to work out what the person should do.
Each step is a pair:
skillthe slug of a Well skill, exactly as well_search_skill lists it. A slug the catalog does not hold is refused, and the refusal names the slugs it does.promptone natural sentence, 1 to 160 characters, written from that skill's own quoted trigger utterances. Write what the PERSON would say, in their words, not an instruction to yourself.
REFUSED rather than rendered:
a step naming a brick a flow invokes (
define-workspace,define-period,normalize-currency) or one of the two skills that call this tool (signing-back,whats-next): nobody sends those, so rank another skill in its placea prompt that starts with "/": the host reads it as a command, not as a message
a prompt containing "<": the host can read it as markup
a prompt containing a line break: a tile sends one line
fewer or more than 5 steps: the card is a fixed list
the same skill in two steps (reason "skill_repeated"): two tiles of one skill look the same, and the digest never repeats a skill: pass its
suggested_stepsas they are
In a demo workspace, after a skill ran there in this conversation, the result can lead with one step of the server's own, kind: "continue_on_real": it offers the same skill on the person's own company, named in target_workspace. It appears only when the person already holds that workspace. It takes the first tile. A step of yours that names the same skill drops, and when none does your fifth drops. Your other steps keep their order. It is offered once per conversation. Pass your five as usual: never add it, and never leave a step out for it.
Clicking a tile records that pick on this connection. Read it back with well_wait_for_selection({ kind: "next_step", timeout_s: 60 }) in this same turn: on "selected", take selection.next_step.prompt as the person's own message and start selection.next_step.skill at once, loading it with well_get_skill. A click on the continue tile has also moved the conversation to the person's own workspace, which selection.workspace_id names: start the skill there, with no second workspace picker. When no turn is waiting, the card sends the sentence into the conversation itself as the person's own message. That is the recovery, not the plan: it arrives as a fresh turn that starts from nothing you already hold. Every row stays clickable while the card is on screen, and a click changes nothing about the row: a person who takes a second step later finds the same five tiles.
When the card renders, the five tiles are already in front of the person and the card sits where this call sits in the turn: write everything you have to say BEFORE calling. After it, the only thing that follows is the well_wait_for_selection call the result's next_step field spells out. Prose in place of that call ends the turn, and the click then has to restart the work from a new message rather than continue this one.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| steps | Yes | Exactly 5 steps, in the order the card lists them. | |
| 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. | |
| first_session | No | True only when the welcome skill draws the card of a person's first session: each tile then shows its sentence as the title. Omit it on every other card. | |
| 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 | Yes | ||
| error | No | ||
| steps | Yes | ||
| reason | Yes | ||
| 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. | |
| first_session | Yes | ||
| 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. | |
| 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. |