Ask a human to choose options
elicit_selectionAsk a human to choose one or more options from a caller-supplied list (disambiguation, record matching, picking work items). Async like elicit_approval: returns a pending request decided on the hosted review page; the chosen option ids come back via elicit_result as selectedIds. Options render as rows of a table the Liquid templates and css can customize. Defaults to single-select — raise maxSelections for multi-select.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| css | No | Custom CSS injected on the review page to style the option table. | |
| labels | No | Relabel or localize the action buttons (submit, decline). Each label is trimmed, 1-40 characters; unknown keys are rejected. Button placement and styling stay fixed. | |
| message | Yes | The instruction shown above the option list — say what the reviewer is choosing and why. | |
| options | Yes | The choices (1-500). Each option is an object with a required unique `id` (returned in `selectedIds`) plus any extra keys, which `rowTemplate` / `hoverTemplate` can reference (e.g. {{ option.name }}). | |
| rowTemplate | No | LiquidJS template producing the <td> cells of one option row; the option is exposed as `option` (e.g. <td>{{ option.name }}</td><td>{{ option.score }}</td>). Any link must carry target="_blank" — without it the click replaces the option table with the linked page and the reviewer loses the form. Default: a single cell of `option.label`, falling back to `option.id`. | |
| hoverTemplate | No | LiquidJS template for a per-option hover/details card; the option is exposed as `option`. Omit for no hover card. | |
| maxSelections | No | Most options the reviewer may pick (default 1 = single-select; clamped to the option count). | |
| minSelections | No | Fewest options the reviewer must pick to submit (default 1; 0 allows none). | |
| footerTemplate | No | LiquidJS template producing the table footer rows (no variables). Omit for no footer. | |
| headingTemplate | No | LiquidJS template producing the <th> cells of the table header (no variables). Omit for no header row. | |
| expiresInSeconds | No | How long the request stays decidable, in seconds (default 3600, clamped 60-604800 — 1 minute to 7 days). |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| status | Yes | Always `pending` at creation. | |
| expiresAt | Yes | When the request stops being decidable (timestamp). | |
| reviewUrl | Yes | URL of the hosted review page where a human decides this request. | |
| elicitationId | Yes | Unique id of the created request — pass it to elicit_await / elicit_status / elicit_result / elicit_cancel. | |
| elicitationDelivered | Yes | True when the request was also pushed to the connected client as a url-mode elicitation; when false, surface `reviewUrl` to the human yourself. |