MCP tool contract

The brain is the only source of tool schemas: clients read them from tools/list, and there is no client-side catalog. Wire names are dotted (workflow.status_and_next); if you see underscores (workflow_status_and_next, mcp_merv_workflow_status_and_next) that’s your client renaming them. Live JSON schemas come from TOOL_MANIFEST in merv/src/merv/brain/surface/tools/contracts.py. Internal tools are still listed by tools/list but flagged hidden: true. Feature gating removes families outright: storage tools when object storage is off, sandbox tools when sandboxes are off, and the two MLflow tools unless tracking is enabled (off by default). 54 tools: 43 public, 11 internal. A default deployment (storage on, tracking off) exposes 41 public tools; turning storage off removes 6 more. Almost every tool takes project_id (required).

Start here

Tool	Purpose
`workflow.status_and_next`	The canonical entrypoint. Inputs: `project_id`, optional `experiment_id`. Without an experiment: workflow guidance plus bounded project context (metadata, latest published reflection, literature summary, every claim, one summary per experiment). With one: the experiment, latest plan, latest report, and current-attempt artifact references
`project`	Navigation for this credential, dispatched on `action`: `list` · `current` · `create` · `overview`. External `mk_` keys can’t `create`

The `workflow.status_and_next` envelope

Key	Notes
`current_gate`	One of the gate codes below
`next_action`	One of the action names below
`allowed_actions`	Tool names the agent may call now
`blocked_actions`, `missing_evidence`, `revision_context`	Why it can’t do more yet
`review_gate`	When a review is due: `role`, `skill`, `target_type`, `target_id`, `status` (`none` · `requested` · `started` · `attested_blocked`), `read_only: true`, plus `request_id`/`expires_at` when a request exists
`artifact_guidance`	Role, template path, and guidance for the next artifact
`live_experiments`	When relevant

Gate codes

Experiment: plan_required, design_review_required, execution_ready, results_report_required, logic_graph_required, experiment_review_required.
Reflection: reflection_roster_incomplete, reflections_complete, project_graph_required, reflection_doc_required, change_spec_required, reflection_review_required, consolidation_proposal_required, consolidation_review_required, central_advance_required.
Plus <review>_passed once a review passes.

next_action values

Experiment: write_and_submit_plan, submit_design_for_review, mark_ready_to_run, start_running, run_experiment_and_retain_results, write_and_submit_results_report, write_and_submit_logic_graph, submit_results_for_review, complete_experiment, retry_running, mark_experiment_failed, abandon_experiment.
Reflection: fan_out_reflection_subagents, submit_reflections, update_and_submit_project_graph, write_and_submit_reflection_doc, write_and_submit_change_spec, submit_reflection_artifacts, begin_consolidation, submit_consolidation_proposal, advance_central, wait_for_central_advance, wait_for_runner_publish, abandon_reflection.
At a review gate: launch_<role>_reviewer, wait_for_<role>_review — for design, experiment, reflection, consolidation.

Experiments

Tool	Required	Optional
`experiment.create`	`project_id`, `name` (3–48 chars, folder-safe; becomes `experiments/<name>/`)	`intent` (one-line headline, the UI title), `tested_claim_ids`, `status`. Deprecated aliases (`title`, `hypothesis`, `design`, `success_criteria`, `risks`) still parse — put that content in `plan.md`
`experiment.transition`	`project_id`, `experiment_id`, `transition` (one of `allowed_actions`)	`evidence` (dict)
`experiment.exhibit`	`project_id`, `experiment_id`	Read-only preview of the metrics exhibit built from pinned result files (`metrics.json`, `results.json`, `results/*.json`)

Artifacts

Tool	Required	Optional
`artifact.submit`	`project_id`, `target_type`, `target_id`, `role`, `path`	`lens_id`, `title`. Returns upload commands to run — the uploaded bytes are the evidence
`artifact.find`	`project_id`	`artifact_id`, `artifact_ids`, `include_content` (default false), `target_type`, `target_id`, `role`

Claims and candidates

Tool	Required	Optional
`claim.create`	`project_id`, `statement`	`scope`, `confidence` (`low` · `medium` · `high`; default `medium`)
`claim.update`	`project_id`, claim id	status, confidence
`candidate.submit`	`project_id`, `name`, `source_kind` (`artifact` · `storage_object` · `experiment_workspace`), `source_ref`, `metrics`, `primary_metric`, `validation_summary`, `idempotency_key`	`expected_sha256`, `higher_is_better` (default true)
`candidate.stage`	`project_id`, `candidate_id`, `stage_kind` (`artifact` · `storage_object` · `evaluator_receipt`), `stage_ref`	`content_sha256`, `manifest_sha256`
`candidate.promote`	`project_id`, `candidate_id`, `expected_champion_id` (from `candidate.list`; empty string when no champion exists), `reason`	Compare-and-swap; refresh and retry if it fails
`candidate.list`	`project_id`	Candidates, append-only promotion history, current champion

Reviews

Tool	Required	Optional
`review.request`	`project_id`, `target_type` (`experiment` · `reflection`), `target_id`, `role` (`design_reviewer` · `experiment_reviewer` · `reflection_reviewer` · `consolidation_reviewer` · `human` · `automated_check`)	`reason`, `producer_session_id` (default `main`). The capability plaintext is returned only in this response
`review.start`	`review_request_id`, `reviewer_capability`, `caller_session_id`	`declared_agent`. Scope: capability, not project
`review.submit`	`review_session_id`, `verdict` (`pass` · `needs_changes` · `fail`), `synopsis`	`return_to` (`planned` · `running` · `reflecting` · `synthesizing` · `consolidating`), `notes`, `findings`, `evidence`

Reflection and consolidation

Tool	Purpose
`reflection.create`	Open a project reflection wave
`reflection.get`	Roster, per-lens coverage, TLDRs of current-attempt artifacts, prior published graph/documents, snapshotted terminal-experiment reports and graphs; `include_content=true` only for a focused deep dive
`reflection.transition`	`submit_reflections` · `submit_reflection_artifacts` · `begin_consolidation` · `publish` · `abandon`
`consolidation.get`	The authoritative reflection plus a slim immutable experiment packet: branches, base/head SHAs, result summaries, proposal coverage, prior consolidation-review feedback
`consolidation.submit`	Submit one immutable consolidation proposal

Sandboxes

All take project_id; most accept experiment_id or sandbox_uid to pick the machine.

Tool	Notable inputs
`sandbox.options`	`gpu`, `region` filters
`sandbox.request`	`public_key` (required); `provider`, `instance_type`, `region`, `gpu`, `cpu`, `memory`, `time_limit`, `additional` (default false), `experiment_id`
`sandbox.get`, `sandbox.list`	—
`sandbox.attach`	`experiment_id`, `sandbox_uid` (both required)
`sandbox.extend`	`seconds` (default 1800)
`sandbox.runs`	`wait_seconds` (default 0; recommended ≤ 45; server cap 300)
`sandbox.terminal`	`tail`, `since`
`sandbox.pull_outputs`	`paths`
`sandbox.release`	`confirm_retained` (default false — the first call returns a retention checklist and destroys nothing)

Storage, literature, feed

Tool	Purpose
`storage.submit`	Required `path`, `kind` (`dataset` · `model` · `other`), `sha256`, `size_bytes`; optional `name`, `content_type`, `producing_experiment_id`, `producing_run`, `source_uri`, `notes`. Returns a one-line upload command
`storage.fetch`	Required `path`; `object_id` or `name` to pick the object. Returns a one-line download command
`storage.find`	Optional `object_id`, `name`, `version`, `kind`, `status`, `include_expired`, `limit`, `offset`, `compact`, `include_download`
`storage.object`	`object_id`, `action` (`pin` · `unpin` · `renew` · `delete`)
`litreview.view`	Read the living literature review
`litreview.edit`	One targeted change per call — add, edit, delete, or reorder one thing; never rewrite the document
`litreview.cite`	Register a paper — exactly one of `url` / `doi` / `arxiv_id`; optional `targets` (≤ 20, types `litreview_section` · `experiment` · `claim`), `note`, `title`
`feed.register`	`handle` (required); `role` (`main` · `reviewer` · `lens`), `bio`, `new_voice`, `session_id`
`feed.post`	`handle`, `text` (required); `kind` (`finding` · `kill` · `hunch` · `idea` · `paper` · `question` · `bottleneck` · `direction` · `status`), `attachments`, `thread`, `in_reply_to`, `quote_of`
`feed.list`	`limit` (default 30), `before_seq`

Off by default

mlflow.context, mlflow.finalize_run — served only when tracking is enabled.

Internal (listed, hidden)

project.list · project.get · project.update · experiment.list · experiment.get_state · claim.list · reflection.list · review.status · sandbox.health · storage.put_object · storage.complete_upload. Agents don’t need them; the UI and recovery paths do.

Start

Concepts

Guides

Clients

Reference

Self-host

Start here

The `workflow.status_and_next` envelope

Experiments

Artifacts

Claims and candidates

Reviews

Reflection and consolidation

Sandboxes

Storage, literature, feed

Off by default

Internal (listed, hidden)

​Start here

​The workflow.status_and_next envelope

​Experiments

​Artifacts

​Claims and candidates

​Reviews

​Reflection and consolidation

​Sandboxes

​Storage, literature, feed

​Off by default

​Internal (listed, hidden)

Start here

The `workflow.status_and_next` envelope

Experiments

Artifacts

Claims and candidates

Reviews

Reflection and consolidation

Sandboxes

Storage, literature, feed

Off by default

Internal (listed, hidden)