# MCP tools reference > The four cross-review MCP tools, their parameters, results, the next values of review_wait, and the errors they return. The installer registers an MCP server named `cross-review` with Claude Code and Codex. It exposes four tools that run one review: `review_begin`, `review_wait`, `review_reply` and `review_end`. The skills call them in that order. Each tool does the same work as the matching [CLI verb](https://cross-review.tlelabs.com/docs/reference/cli/#verbs-the-skills-use). | Tool | Starts or continues | Returns | | -------------- | --------------------------------------------------------- | ---------------------------------------------------------------------------- | | `review_begin` | A new session and its round 1. | `session_dir`, `round`, `status`, and `analysis_prompt` for peer skills. | | `review_wait` | Waits for the current round to end (or for a time limit). | The round’s poll result plus `next` and `next_reason`. | | `review_reply` | The next round, on the same reviewer thread. | `status`, `session_dir`, `round`, `thread_id`. | | `review_end` | Finalizes the session and stops it. | `status`, `session_dir`, `finalized`, and `verdict` or `error` when present. | Every tool keeps its state on disk, so a review survives the MCP server exiting. Call `review_wait` again with the same `session_dir` to continue. > **Note:** > > Session state lives under `.cross-review/sessions/` in the repository under review. See [session files](https://cross-review.tlelabs.com/docs/reference/session-files/). ## review_begin Starts a session, renders round 1 from the skill’s template, and starts the reviewer in the background. | Parameter | Type | Required | Description | | ----------------- | ---------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `skill` | enum | Yes | `review-plan`, `review-impl`, `review-think` or `review-pr`. | | `mode` | string | For `review-impl` | `working-tree` or `branch`. Leave it out for the other skills. | | `input` | string | Yes | Markdown with the placeholder values. Optional front matter holds `NAME: value` lines between `---` lines. Each multi-line value is a `## NAME` section, for example `## USER_REQUEST`. | | `working_dir` | string | Yes | Absolute path of the repository under review. | | `model` | string | No | Reviewer model. When left out, the [settings](https://cross-review.tlelabs.com/docs/reference/configuration/) decide, and then the reviewer’s own default. It is kept for later rounds. | | `effort` | string | No | Reasoning effort. When left out, the settings decide, and then `high`. It is kept for later rounds. | | `timeout_seconds` | positive integer | No | Runner deadline for the reviewer. Default 18000 (5 hours). | | `reviewer` | enum | No | Reviewer CLI. Only `codex` today. When left out, the settings decide. | Result, as JSON text: ```json { "session_dir": "/path/to/repo/.cross-review/sessions/review-impl-20261016-001", "round": 1, "status": "running" } ``` - `analysis_prompt` is present for the peer skills (`review-think`, `review-pr`). The orchestrator writes its own analysis from it before it compares. - `dashboard_url` is present when the dashboard follows reviews (`open_dashboard`). `dashboard_error` replaces it when the dashboard could not open the session. The review runs either way. ## review_wait Waits up to `max_wait_seconds` for the reviewer. It returns early when the round ends. | Parameter | Type | Required | Description | | ------------------ | ------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `session_dir` | string | Yes | The `session_dir` that `review_begin` returned. | | `max_wait_seconds` | integer, 0 or more | No | How long this call waits. The default comes from the server’s `REVIEW_WAIT_DEFAULT_S` environment variable. The installer sets it to 270; without it the default is 50. | The result has the poll fields of the round and two more: | Field | Meaning | | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | `status` | `running`, `completed`, `failed`, `stalled` or `timeout`. `running` also comes back when `max_wait_seconds` runs out first. | | `round` | The round number. | | `elapsed_seconds` | Seconds since the round started. | | `thread_id` | The reviewer thread, once known. | | `review` | The parsed review when the round completed: `verdict`, and the `blocks` (issues). | | `activities` | What the reviewer did since the last call. | | `error`, `failure_reason`, `timeout_reason`, `recoverable`, `progress_observed` | Present on a failed, stalled or timed-out round. | | `next` | What the orchestrator does next. See the table below. | | `next_reason` | Why. See the table below. | ### next values | `next` | What the orchestrator does | | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `running` | Calls `review_wait` again. `next_reason` is `reviewer_running`. | | `respond` | Fixes the valid findings and rebuts the others, then calls `review_reply`. Plan and implementation reviews only. `next_reason` is `open_issues`, or `verdict_` followed by the verdict in lower case. | | `cross_check` | Peer skills only. Compares the findings with its own analysis, then calls `review_reply`, or `review_end` with an `outcome`. `next_reason` is `peer_verdict_is_advisory`. | | `done` | Calls `review_end`. `next_reason` is `approved` (plan and implementation reviews), or `stalemate`. | | `ask_user` | Asks the user what to do. `next_reason` is `missing_verdict`: the round ended with neither a verdict nor findings. | | `stopped` | The round ended without a usable review. `next_reason` is `recoverable_timeout` when the runner deadline passed after progress and the thread can be resumed. Otherwise it is the failure reason, such as `stalled`, `turn_failed` or `reviewer_process_exit`. | > **Note:** > > A plan or implementation review ends when the verdict is `APPROVE`. A peer skill’s round ends with an advisory status (`CONTINUE`, `CONSENSUS` or `STALEMATE`) that never ends the session by itself. The orchestrator ends it with `review_end` and an `outcome`. ## review_reply Sends the next round. The skill’s round 2+ template is filled from `input` and sent to the same reviewer thread. | Parameter | Type | Required | Description | | ------------- | ------ | -------- | -------------------------------------------------------------------------- | | `session_dir` | string | Yes | The session. | | `input` | string | Yes | The next round’s placeholder values, in the same format as `review_begin`. | | `model` | string | No | Changes the stored model for later rounds. | | `effort` | string | No | Changes the stored effort for later rounds. | When `model` and `effort` are left out, the stored values are used. The sandbox is always the one stored in the session. Result: `status` (`started`), `session_dir`, `round` (the new round number), and `thread_id`. ## review_end Finalizes the session when it can, then stops the reviewer. | Parameter | Type | Required | Description | | ------------- | -------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- | | `session_dir` | string | Yes | The session. | | `outcome` | `consensus` or `stalemate` | No | Required for peer skills whose exit rule is met. Plan and implementation reviews take the verdict from the last round. | Result: `status` (`ended`), `session_dir`, `finalized` (true when `meta.json` was written), and `verdict` when it was set. - A plan or implementation review is finalized only when its last round reached `done`. A peer review is finalized only with an `outcome`. Otherwise the call just stops the session and returns `finalized: false`; this is a normal result, not an error. - When finalizing was tried and failed, the session is still stopped, and the result also has an `error` field and `isError` set. ## Errors A failed call returns the text `{"error": ..., "code": ...}` with `isError` set to true. The most common codes: | Code | Meaning | | --------------------- | ------------------------------------------------------------------------------------- | | `CONFIG_INVALID` | A settings file is broken. No session is created. Fix the file named in the message. | | `INVALID_INPUT` | A parameter is missing or wrong, for example a `review-impl` call without `mode`. | | `UNKNOWN_SKILL` | The skill is not one of the four review skills. | | `REVIEWER_NOT_FOUND` | The `codex` CLI is not in `PATH`. | | `INVALID_SESSION` | `session_dir` does not hold a readable session. | | `ROUND_STILL_RUNNING` | `review_reply` was called while the round is still running. Call `review_wait` first. | Other codes come from the runner and are passed through unchanged.