Well

Propose next steps

well_propose_next_steps

Read-only

Put five next steps on a card, as five lines the person can send.

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 sentence beside 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. 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:

skill the 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.
prompt one 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 place
a 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 row carries one line
fewer or more than 5 steps: the card is a fixed list

Clicking a line 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. 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 lines.

When the card renders, the five lines 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

TableJSON Schema

Name	Required	Description
`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.
`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

TableJSON Schema

Name	Required	Description
`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.
`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.
`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.

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedSep 22, 2026

addedInput schema / properties / conversation_id

Added value: +{
+  "description": "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.",
+  "type": "string"
+}

addedOutput schema / properties / conversation_id

Added value: +{
+  "description": "The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.",
+  "type": "string"
+}

addedOutput schema / properties / conversation_id_note

Added value: +{
+  "description": "Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.",
+  "type": "string"
+}

addedOutput schema / properties / conversation_id_source

Added value: +{
+  "description": "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened.",
+  "enum": [
+    "host_meta",
+    "argument",
+    "minted"
+  ],
+  "type": "string"
+}

AddedSep 11, 2026

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Even with readOnlyHint=true and destructiveHint=false already in annotations, the description adds substantial behavioral detail: it does not rank, it refuses invalid slugs and malformed prompts, it enforces exactly five steps, it records clicks, it defines the recovery fallback when no turn is waiting, and it mandates that all prose be written before the call. There is no contradiction with the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but front-loaded with the core purpose and the crucial 'ranks nothing' caveat. Each paragraph covers a distinct concern: source and ordering, pair semantics, refusal cases, selection flow, and call sequencing. Some schema-level prompt constraints are repeated, making it slightly verbose, but the length is mostly earned given the number of failure modes the tool must handle.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity, the description is remarkably complete: it specifies when to call, when not to call, how to construct each step, what gets refused, how clicks are handled, how to read the selection with well_wait_for_selection, and how to sequence prose before the call and the follow-up call after it. Since an output schema exists, not documenting return values is acceptable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although the schema has 100% description coverage, the tool description adds critical parameter semantics: pass the five skills in the digest's order, write prompts in the person's language from the skill's quoted utterances, use the skill slug exactly as well_search_skill lists it, and produce exactly five steps. It also explains the reasoning behind prompt constraints like no leading '/', no '<', and no line breaks — going beyond the bare schema constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a concrete action and outcome: 'Put five next steps on a card, as five lines the person can send.' It immediately distinguishes itself from siblings by stating 'This tool ranks nothing' and by pointing to well_get_session_digest's suggested_steps as the source of the five skills, so an agent can tell exactly when this card-rendering tool applies.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is made explicit: 'Call it at the END of a skill that tells you to, never to work out what the person should do.' It also gives a clear negative condition — when suggested_steps is empty or shorter than five, do NOT call the tool and instead say next steps cannot be proposed. This is specific, actionable guidance that prevents misuse.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Well tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?