product: assert audience: test-developer, operator, ai-assistant authority: normative

MCP Tools — Operator Prompts

A type: prompt step blocks its run until somebody answers it. These tools let a caller that is not standing at the station see that a run is waiting, read exactly what it is asking, and answer it with one of the buttons the prompt declares.

The answer goes through the same station-side path as a click in the Test Monitor: the button is checked against the prompt's declaration, the declared action decides the verdict, and the answer is recorded against the execution with the identity you give. A click and a remote answer cannot differ.

For runs where nobody should have to answer at all, start the test with unattendedMode: true instead (see unattended-mode.md). The tools here are for runs that do need a decision, taken by someone who is not at the screen.

All tool responses include a top-level station field containing the StationLabel configured for this server instance.

See also: tools-reference.md for the full tool index, and ui/prompt-input.md for how prompts are authored.

The prompt shape

get_pending_prompt, get_test_status (pendingPrompt) and poll_test_progress (pendingPrompts[]) all describe a pending prompt the same way:

Field	Meaning
`executionId`	The run that is waiting
`promptId`	The prompt's identity (its step execution id). Pass it to `answer_prompt`
`stepName`	The prompt step's name
`title`, `message`	What the operator is being asked
`imageUrl`, `videoUrl`	Media shown with the prompt, if any
`buttons[]`	The declared buttons: `name` and `action` (`Continue`, `Pass`, `Fail`, `Abort`)
`defaultButton`	The button Enter presses in the Test Monitor
`input`	The value-input control, if any: `mode`, `required`, limits, `unit`, `options`, `defaultValue`
`timeout`	`seconds` and `defaultButton` when the prompt auto-submits; `null` when it waits forever
`raisedAtUtc`	When the run started waiting

A prompt that declared no abort button still shows Cancel (action Abort): the engine adds one to every prompt so a run can always be stopped from the dialog.

`get_pending_prompt`

Returns the prompt a running execution is blocked on, or every prompt pending on the station.

Parameter	Type	Required	Description
`executionId`	GUID	No	The execution to check. Omit to list all pending prompts on the station

Returns: with executionId — pending (bool) and prompt (the shape above, or null); without — count and prompts[]

Calls: GET /api/testexecution/{executionId}/prompt (200, or 204 when nothing is pending); GET /api/testexecution/prompts

`answer_prompt`

Presses one of the pending prompt's declared buttons.

Parameter	Type	Required	Description
`executionId`	GUID	Yes	The execution whose prompt to answer
`button`	string	Yes	Name of a declared button (case-insensitive)
`promptId`	GUID	No	The prompt being answered. Recommended: an answer carrying the id of a prompt that is no longer current is refused instead of landing on the next one
`inputValue`	string	No	Value for the prompt's input control. Required when the prompt's input is `required`, unless the button aborts
`respondedBy`	string	No	Who is answering. Recorded against the execution

Returns: accepted (bool), outcome, message, promptId, button (the declared name that was applied), action, respondedBy, declaredButtons[]

`outcome`	HTTP	Meaning
`Accepted`	200	Applied; the step resumes with this answer
`UnknownButton`	400	Not a declared button — `declaredButtons` lists the valid ones
`InputRequired`	400	The prompt needs `inputValue`
`StalePrompt`	409	`promptId` is not the prompt the run is waiting on now
`NoPendingPrompt`	404	Nothing is waiting: never prompted, already answered (by anyone), or the run ended

A refused answer leaves the run waiting. Two answers racing for the same prompt cannot both apply: the first wins and the second is told NoPendingPrompt.

Calls: POST /api/testexecution/{executionId}/prompt/answer with { "stepExecutionId", "button", "inputValue", "respondedBy", "source": "Mcp" }

Recorded as: an execution log line — Prompt "<step>" answered "<button>" (<action>) by <respondedBy> via Mcp — the Response measurement every prompt records, and the RespondedBy output variable.

Typical flow

start_test(yamlFilePath = "...", serialNumber = "C114305")
get_test_status(executionId)            → waitingForOperator: true, pendingPrompt: { promptId, buttons: [Done, Cancel] }
answer_prompt(executionId, button = "Done", promptId = "...", respondedBy = "daniel@esharp.se")
wait_for_test_completion(executionId)

Only answer a prompt whose instruction you have actually carried out, or been told has been carried out: a prompt that says "move the cable" is asking for a physical action at the bench, and answering it does not perform that action.