# MCP tools Realm's MCP server has 11 tools. An AI assistant calls them to find a workflow, start a run, do its steps and read its state. This page gives each tool's parameters and its reply. The tools and their parameters were read from the server's own `tools/list` reply, and every reply shown came from a call. | Tool | What it does | | ------------------------------------------------- | ---------------------------------------------------------------------------- | | [`list_workflows`](#list_workflows) | Lists the registered workflows. | | [`get_workflow_protocol`](#get_workflow_protocol) | Describes one workflow's steps and the rules for running it. | | [`start_run`](#start_run) | Starts a run. | | [`start_run_batch`](#start_run_batch) | Starts several runs of one workflow. | | [`execute_step`](#execute_step) | Does one step, with the assistant's answer. | | [`submit_human_response`](#submit_human_response) | Passes on a person's choice at a gate. | | [`advance_run`](#advance_run) | Runs the guards and automatic steps a run owes (added after version 0.46.0). | | [`get_run_state`](#get_run_state) | Returns where a run stands. | | [`abandon_run`](#abandon_run) | Ends an open run. | | [`create_workflow`](#create_workflow) | Makes a workflow from a list of steps and starts a run of it. | | [`append_trace`](#append_trace) | Records notes about a step before the step is done. | To connect an assistant, see [Connect an MCP client](https://realmengine.dev/docs/guides/connect-an-mcp-client.md). ## Calling a tool - **A required parameter that is missing, or a value of the wrong type, is refused by the MCP layer.** The call is marked as an error and its text is, for example, `MCP error -32602: Input validation error: Invalid arguments for tool execute_step: Required at command`. - **A parameter the tool does not have is ignored, without a warning.** A `start_run` call with `idempotencyKey` in place of `idempotency_key` started a run with no key. `create_workflow`, `submit_human_response` and `advance_run` are the exceptions: each names what it ignored, in `warnings`. - **Every other refusal is an ordinary reply** with `status: "error"`, described next. ## The reply `start_run`, `execute_step`, `submit_human_response`, `advance_run` and `create_workflow` reply with one JSON object of the same shape. `start_run_batch`, `append_trace`, `get_run_state` and `abandon_run` use that shape when they refuse a call, except that a refusal from `get_run_state` or `abandon_run` has no `run_version`. `list_workflows` refuses with its own fields — `status`, `error_code`, `error_details`, `errors`, `agent_action` and `hint`, with `workflows` and `unreadable` empty — and `get_workflow_protocol` refuses with plain text, marked as an error, as the MCP layer does (above). The examples on this page leave out fields that are empty, and show a long `next_actions` list as `"…"`. | Field | Always present | Holds | | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `command` | Yes | The tool, or for `execute_step` and `submit_human_response` the step. A refused answer that names no step — a gate ID that is not the open one, a run with no question open — says `submit_gate`, a word older than `submit_human_response`. An answer the tool refuses before the engine reads the run says `submit_human_response`: a run ID that does not exist (`STATE_RUN_NOT_FOUND`), or a run or workflow that cannot be read. | | `run_id` | Yes | The run: the ID the call named, also when no run has that ID (the refusal is `STATE_RUN_NOT_FOUND`). Empty (`""`) when `start_run`, `start_run_batch` or `create_workflow` refuses the call, which then makes no run: a workflow that is not registered (`STATE_WORKFLOW_NOT_FOUND`), params its `params_schema` refuses (`VALIDATION_INPUT_SCHEMA` from `start_run`, `VALIDATION_BATCH_ITEMS` from `start_run_batch`), a batch over `max_items` (`VALIDATION_BATCH_TOO_LARGE`), an `idempotency_key` that a run still going holds when `on_live_match` is `fail` (`STATE_RUN_ALREADY_ACTIVE`, whose `errors` name that run), and `create_workflow` refusing its steps. | | `run_version` | Yes, except on a refusal from `get_run_state` or `abandon_run` | A number that rises each time the run is changed. `0` when the reply names no run's state: a run ID that does not exist, and every refusal that replies `run_id: ""`. A refusal of an agent step's answer for its `input_schema` or `output_schema` (`VALIDATION_INPUT_SCHEMA`, `VALIDATION_OUTPUT_SCHEMA`) counts the refusal on the run, a write, and replies the number from before that write, so the next reply that reads the run shows a number at least one higher even when nothing else changed it. `realm agent`'s repair of an answer reads that. The refusal that uses up the step's limit (`VALIDATION_EXHAUSTED`) replies the number after its writes. | | `status` | Yes | `ok`, `error`, `blocked` or `confirm_required`. See below. | | `context_hint` | Yes | One sentence about what has just happened. | | `next_actions` | Yes | The calls that can be made next; an open question is named by its answer. Empty when nothing can be called now (see `ok` below). | | `warnings`, `errors` | Yes | Lists of messages. | | `data`, `evidence` | Yes | Empty in MCP replies, except that `create_workflow` puts the new `workflow_id` in `data`. Read the run with `get_run_state`. | | `run_phase` | With a run | The run's phase after the call. | | `error_code` | On an error, except `create_workflow`'s refusal of its steps (its `errors` say what is wrong) and an `abandon_run` refusal of an error that carries no code | A code such as `VALIDATION_INPUT_SCHEMA`. See [Error codes](https://realmengine.dev/docs/reference/error-codes.md). | | `error_details` | On some errors, and on a late answer that names the choice the question's expiry recorded | Details that depend on the code, such as the schema rules that were broken; on a late answer that found the expired question still open, when its time was up (`expired_at`) and how long before the call (`overdue_ms`); on that late answer, the choice the expiry recorded and `resolved_by`. | | `agent_action` | On every `error` and `blocked` reply. On an `ok` reply only as `stop`: from `execute_step` on a run that has already ended, and from a call that finds the run ended by another process meanwhile, at a guard step or at a step it picked (added after version 0.46.0 for a step it picked) | What the caller should do. See below. Never on `confirm_required`, and never on another `ok` reply: on a run that had ended before the call, `advance_run` replies `ok` without it, and so does `submit_human_response` repeating the choice its gate recorded (`… was already resolved with choice '' — no action was taken.`, or the expiry's sentence when the question's expiry recorded it). See [A run that has ended](#a-run-that-has-ended). | | `retry_after` | With `wait_and_proceed` | How many seconds to wait. | | `blocked_reason` | With `blocked`, and on a refusal for an invalid `trust` | `eligible_steps`, the steps that can be called by name, and a `suggestion`. | | `gate` | With `confirm_required` | The open gate: `gate_id`, `step_name`, `preview`, `choices`, and when set `display`, `agent_hint`, `expires_at`, and `claim_token` when the store gave one. See [The claim token](#the-claim-token). | | `deduped` | From `start_run` and `create_workflow` | `true` if an existing run was returned in place of a new one. | | `chained_auto_steps` | When `auto` or `guard` steps ran in the call | Each such step that finished, and the run's phase after it. An `auto` step's entry also has `warnings` when that step's own call gave any (such as the expiry line of an `execute_step` call that carried out an expired question first); the reply's `warnings` lists them too. A step that stopped the call is not listed: it is in `stopped_step`. From `start_run`, `execute_step` and `advance_run` (added after version 0.46.0). | | `stopped_step` | From `execute_step`, `start_run` and `advance_run` (added after version 0.46.0), on an `error`, `blocked` or `confirm_required` reply that a step's call produced | The step the call stopped at. When it is not the step you called, the step you called finished and the engine then went on to this one. From `start_run`, the `auto` step the call stopped at. Added in 0.46.0. | | `guards` | When the call's write decided guard steps; from `advance_run`, only a guard that ended the run | Each guard and its `outcome`: `pass`, `abort` or `resolution_error`. See [Guards in a reply](#guards-in-a-reply). | | `ended_by` | When one of those guards ended the run | `arm`, the guard's `step`, and a `reason` when there is one. | | `answer_recorded` | From `submit_human_response`, for an answer that came after the gate's time was up | `false`. It is never `true`: an answer that was recorded leaves the field out. | | `gate_claim` | From `submit_human_response`, on every `ok` reply | Whether the answer came from the conversation that opened the question: `proof`, a `cause` for two of its values, and `opened_by`. See [The claim token](#the-claim-token). | | `adopted_own`, `adopted_anonymous`, `preserved_foreign` | From `execute_step` on an agent step | How many trace entries sent with `append_trace` were attached to the step. | | `settled_by_default`, `defaulted_steps` | When a step was given its default output | See [Agent-step controls](https://realmengine.dev/docs/reference/workflow/agent-step-controls.md#validation_exhaustion). | | `diagnostics` | From `create_workflow` | What was ignored in the request, as a list. | ### Guards in a reply A guard step is never called. It is decided inside the write that makes it ready, and the reply to that call says what it did: - `guards` lists each guard the write decided, in order, with its `outcome`. - From `start_run` and `execute_step`, each of those guards is also in `chained_auto_steps`. From `submit_human_response` they are in `guards` only. - When a guard ended the run, `ended_by` holds its `arm` (`guard_abort`, `guard_resolution_error` or `guard_pass_complete`) and its `step`, and `context_hint` is one of `Guard step '' aborted the run.`, `Guard step '' failed with a resolution error. Run is terminated.` and `Guard step '' passed and completed the run.` On an answer's reply and `advance_run`'s, the second goes on with the way back in, the guard being a failed step `realm run resume` takes: `To make the failed step runnable again: realm run resume --from ` (added after version 0.46.0) - `ended_by.reason` is the guard's `abort_message` when it aborted, and is left out when the guard has none. For a resolution error it is the error recorded for the guard. For a guard that passed and completed the run there is none. A step that fails can also leave a guard ready. Its reply keeps its own `status`, errors and sentence, and adds `guards` and `ended_by`. A reply from `execute_step`, for an agent step whose answer made a guard abort the run: ```json { "command": "assess", "run_id": "df89a4e4-7a4b-4ff9-aaf0-657f70ae1723", "run_version": 2, "status": "ok", "context_hint": "Guard step 'only_low_risk' aborted the run.", "run_phase": "aborted", "guards": [{ "step": "only_low_risk", "outcome": "abort" }], "ended_by": { "arm": "guard_abort", "step": "only_low_risk", "reason": "High-risk refunds are not paid automatically." }, "chained_auto_steps": [{ "step": "only_low_risk", "run_phase": "aborted" }] } ``` ### `status` | Value | Means | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ok` | The call moved the run forward, or found nothing to do. Follow `next_actions`; an open question is named there by its answer, `submit_human_response`. When it is empty, nothing can be called now: the run has ended, a step cannot run (`context_hint` names it and why, and ends with the way out when the workflow must be corrected), or nothing is ready while a step is in flight in another process (`No step is ready: '' is in flight elsewhere — wait for it, then call get_run_state.`; `get_run_state`'s `step_claims` names the step). Added after version 0.46.0. | | `error` | The call was refused or the step failed. `agent_action` says what to do. | | `blocked` | The step cannot be called now, and `context_hint` says why. `next_actions` names what can be done instead: the agent steps that can be called, `advance_run` when the engine owes work, or the answer to an open question. It is empty when nothing can be done. `blocked_reason.eligible_steps` lists the steps that can be called by name, and may differ from `next_actions`: for example, when the engine owes an `auto` step it can run, `next_actions` offers `advance_run` and `eligible_steps` names the step. When `context_hint` says `Step '' cannot be called now: …`, `blocked_reason.suggestion` says what `next_actions` holds: `Call one of the steps indicated in next_actions instead.` for steps, `Call advance_run, as next_actions says.` for `advance_run` alone, `Call one of the steps indicated in next_actions, or advance_run, instead.` for both, `Answer the open question first, as next_actions says.` for the answer, and `No other step can be called now.` when it is empty (the forms with `advance_run` were added after version 0.46.0). | | `confirm_required` | A human gate is open. `gate` holds what to show the person. | ### `agent_action` | Value | The caller should | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `provide_input` | Correct the input and call the step again. `error_details` says what was wrong. | | `resolve_precondition` | Do what `next_actions` names instead: call what it names (a step, or `advance_run`), or answer the open question it names. The step you called does not run again if it has already completed or been skipped; one that has failed runs again only after [`realm run resume --from `](https://realmengine.dev/docs/reference/cli/realm-run-acting.md#resume) makes it runnable, and `resume` takes only a run that has ended (`failed` or `abandoned`): while the run goes on, end it first with `abandon_run`; any other step runs only once what it waits on holds (its precondition, its dependencies, the answer), and this reply does not promise that it will. | | `report_to_user` | Show the error to the person and wait for guidance. | | `wait_for_human` | Show the error to the person and wait until they say the outside problem is fixed. | | `wait_and_proceed` | Wait `retry_after` seconds, then follow `next_actions`. | | `stop` | Make no further calls for this run. | ### A run that has ended A reply of `execute_step`, `start_run` or `advance_run` on a run that ended — this call's own step failed, or the run had ended before it — ends with the ways back in: for a run an engine failure ended with a failed step `realm run resume` takes, `To make the failed step runnable again: realm run resume --from `; for a run an operator ended (`abandoned`), never that offer — resuming it would erase the operator's ending and its reason — but who ended it and why: `An operator ended this run, with the reason ""; to run the work again, start a new run.`; and for cleanup steps the ending left `pending`, ` Cleanup step left pending: '' — 'realm run drain --force' runs it with code that has its handler.` (while another drainer's lease on it has not passed: ` Cleanup step left pending: '' — held by another drainer's lease until