MCP tools reference

Every registered MCP tool: purpose, who may call it, parameters, and a minimal example.

orch MCP tool reference

Generated by go run ./cmd/orch-docs from mcp.ToolDefs() (client/internal/mcp/server.go) — the same manifest tools/list serves. 56 tools total, 9 Chair-only (denyWorkerFanout, client/internal/mcp/spawn.go); every other tool is callable from any seat.

architecture#

Who may call it: any seat

Purpose: Directory map: symbols and edges per directory.

Minimal example:

{
  "arguments": {},
  "name": "architecture"
}

ask#

Who may call it: any seat

Purpose: Worker: block on a question for the Chair.

Minimal example:

{
  "arguments": {
    "question": "..."
  },
  "name": "ask"
}

ask_answer#

Who may call it: any seat

Purpose: Chair: answer an ask by id; the worker unblocks.

Minimal example:

{
  "arguments": {
    "answer": "...",
    "id": 0
  },
  "name": "ask_answer"
}

ask_list#

Who may call it: any seat

Purpose: Chair: list asks by status.

Minimal example:

{
  "arguments": {},
  "name": "ask_list"
}

code_snippet#

Who may call it: any seat

Purpose: One symbol's body by line range, not the whole file.

Minimal example:

{
  "arguments": {},
  "name": "code_snippet"
}

context_crush#

Who may call it: any seat

Purpose: Crush repetitive success/log noise.

Minimal example:

{
  "arguments": {
    "text": "..."
  },
  "name": "context_crush"
}

context_externalize#

Who may call it: any seat

Purpose: Park bulky text in .orch/context; returns a stub + id.

Minimal example:

{
  "arguments": {
    "text": "..."
  },
  "name": "context_externalize"
}

context_retrieve#

Who may call it: any seat

Purpose: Fetch a full externalized blob by id.

Minimal example:

{
  "arguments": {
    "id": "..."
  },
  "name": "context_retrieve"
}

context_search#

Who may call it: any seat

Purpose: FTS over externalized context chunks.

Minimal example:

{
  "arguments": {
    "query": "..."
  },
  "name": "context_search"
}

decision_get#

Who may call it: any seat

Purpose: Fetch Decision by id.

Minimal example:

{
  "arguments": {
    "id": "..."
  },
  "name": "decision_get"
}

decision_list#

Who may call it: any seat

Purpose: Pending HITL decisions.

Minimal example:

{
  "arguments": {},
  "name": "decision_list"
}

dispatch_worker#

Who may call it: Chair-only

Purpose: Chair: spawn a worker. Async; task_wait before the turn ends.

Minimal example:

{
  "arguments": {},
  "name": "dispatch_worker"
}

entitlements_status#

Who may call it: any seat

Purpose: Active plan, quotas and capability catalog.

No parameters.

Minimal example:

{
  "arguments": {},
  "name": "entitlements_status"
}

evidence_bundle#

Who may call it: Chair-only

Purpose: Chair: verdict, files, commands, tests, usage for a session (markdown).

Minimal example:

{
  "arguments": {
    "session": "..."
  },
  "name": "evidence_bundle"
}

impact#

Who may call it: any seat

Purpose: Symbols in paths plus their callers, two hops.

Minimal example:

{
  "arguments": {},
  "name": "impact"
}

inspect_symbol#

Who may call it: any seat

Purpose: Inspect one shared symbol by name or id.

Minimal example:

{
  "arguments": {
    "name": "..."
  },
  "name": "inspect_symbol"
}

lock_acquire#

Who may call it: any seat

Purpose: Take the shared/** semaphore before editing.

Minimal example:

{
  "arguments": {
    "holder": "...",
    "path": "..."
  },
  "name": "lock_acquire"
}

lock_check#

Who may call it: any seat

Purpose: Deny unless holder holds a valid lock on path.

Minimal example:

{
  "arguments": {
    "holder": "...",
    "path": "..."
  },
  "name": "lock_check"
}

lock_release#

Who may call it: any seat

Purpose: Release a shared/** lock; reindexes and notifies peers.

Minimal example:

{
  "arguments": {
    "holder": "...",
    "path": "..."
  },
  "name": "lock_release"
}

lock_status#

Who may call it: any seat

Purpose: One lock, or every held lock when path is empty.

Minimal example:

{
  "arguments": {},
  "name": "lock_status"
}

memory_conflicts#

Who may call it: any seat

Purpose: Memories sharing type+title but differing in body.

No parameters.

Minimal example:

{
  "arguments": {},
  "name": "memory_conflicts"
}

memory_export#

Who may call it: any seat

Purpose: Export the memory estate as OKF-lite markdown.

Minimal example:

{
  "arguments": {},
  "name": "memory_export"
}

memory_forget#

Who may call it: any seat

Purpose: Soft-expire a memory by id.

Minimal example:

{
  "arguments": {
    "id": "..."
  },
  "name": "memory_forget"
}

memory_import#

Who may call it: any seat

Purpose: Import OKF-lite markdown into the memory estate.

Minimal example:

{
  "arguments": {},
  "name": "memory_import"
}

memory_list#

Who may call it: any seat

Purpose: List active memories.

Minimal example:

{
  "arguments": {},
  "name": "memory_list"
}

memory_recall#

Who may call it: any seat

Purpose: FTS recall over memories, ctxstore chunks and disk memory files. Brief before reinventing.

Minimal example:

{
  "arguments": {},
  "name": "memory_recall"
}

memory_remember#

Who may call it: any seat

Purpose: Store a durable memory. Refused unless it changes behaviour, commits, decides with a reason, or user asked.

Minimal example:

{
  "arguments": {
    "text": "..."
  },
  "name": "memory_remember"
}

memory_sweep#

Who may call it: any seat

Purpose: Expire memories past retention_days.

No parameters.

Minimal example:

{
  "arguments": {},
  "name": "memory_sweep"
}

msg_ack#

Who may call it: any seat

Purpose: Ack a message by id as its recipient.

Minimal example:

{
  "arguments": {
    "id": 0
  },
  "name": "msg_ack"
}

msg_inbox#

Who may call it: any seat

Purpose: Read this seat's inbox; a Chair also gets role mail. wait_sec blocks for mail instead of polling.

Minimal example:

{
  "arguments": {},
  "name": "msg_inbox"
}

msg_peers#

Who may call it: any seat

Purpose: Discoverable sessions; session gives the roster.

Example (from tests):

From peers_live_internal_test.go:47

	out, err := srv.callTool("msg_peers", map[string]any{})
	if err != nil {
		t.Fatal(err)
	}
	row := func(id string) string {
		i := strings.Index(out, `"SessionID":"`+id+`"`)
		if i < 0 {
			t.Fatalf("%s missing from msg_peers: %s", id, out)
		}
		end := strings.Index(out[i:], "}")
		return out[i : i+end]
	}

msg_send#

Who may call it: any seat

Purpose: Send a bus message.

Minimal example:

{
  "arguments": {
    "body": "..."
  },
  "name": "msg_send"
}

msg_stale#

Who may call it: any seat

Purpose: Unread alerts older than older_min minutes.

Minimal example:

{
  "arguments": {},
  "name": "msg_stale"
}

notify_events#

Who may call it: any seat

Purpose: Outbound event catalog (n8n/Zapier).

No parameters.

Minimal example:

{
  "arguments": {},
  "name": "notify_events"
}

search_shared_symbols#

Who may call it: any seat

Purpose: Search the shared symbol registry.

Minimal example:

{
  "arguments": {
    "query": "..."
  },
  "name": "search_shared_symbols"
}

seat_attach#

Who may call it: any seat

Purpose: Dial info for a detached hold. User returns via orch <agent> (auto); MCP cannot steal TTY.

Minimal example:

{
  "arguments": {},
  "name": "seat_attach"
}

seat_detach#

Who may call it: any seat

Purpose: User left the UI, agent keeps running (hosted hold). Call this, not exit.

Minimal example:

{
  "arguments": {},
  "name": "seat_detach"
}

seat_read#

Who may call it: any seat

Purpose: Read seat tail; deep pages more history from the live seat_host.

Minimal example:

{
  "arguments": {},
  "name": "seat_read"
}

seat_report#

Who may call it: any seat

Purpose: Write authoritative seat state (working|ready|blocked|exit).

Minimal example:

{
  "arguments": {
    "state": "..."
  },
  "name": "seat_report"
}

seat_status#

Who may call it: any seat

Purpose: Live seat lifecycle JSON (state/source; maybe_blocked is hint only).

Minimal example:

{
  "arguments": {},
  "name": "seat_status"
}

seat_wait#

Who may call it: any seat

Purpose: Poll until authoritative seat state is in until (not maybe_blocked).

Minimal example:

{
  "arguments": {
    "until": []
  },
  "name": "seat_wait"
}

task_add#

Who may call it: Chair-only

Purpose: Chair: create a Board task.

Minimal example:

{
  "arguments": {
    "title": "..."
  },
  "name": "task_add"
}

task_assign#

Who may call it: Chair-only

Purpose: Chair: assign a task to an agent.

Minimal example:

{
  "arguments": {
    "agent": "...",
    "id": "..."
  },
  "name": "task_assign"
}

task_claim#

Who may call it: any seat

Purpose: Claim a ledger checklist item; fails if a live session holds it.

Minimal example:

{
  "arguments": {
    "holder": "...",
    "item": 0,
    "ledger": "..."
  },
  "name": "task_claim"
}

task_done#

Who may call it: any seat

Purpose: Mark a task done or failed.

Minimal example:

{
  "arguments": {
    "id": "..."
  },
  "name": "task_done"
}

task_list#

Who may call it: any seat

Purpose: List Board tasks. verbose adds body/context/verification.

Minimal example:

{
  "arguments": {},
  "name": "task_list"
}

task_release#

Who may call it: any seat

Purpose: Release a ledger claim; holder must match, or be *.

Minimal example:

{
  "arguments": {
    "holder": "...",
    "item": 0,
    "ledger": "..."
  },
  "name": "task_release"
}

task_run#

Who may call it: Chair-only

Purpose: Chair: dispatch an assigned task as a worker. Async.

Minimal example:

{
  "arguments": {
    "id": "..."
  },
  "name": "task_run"
}

task_wait#

Who may call it: Chair-only

Purpose: Chair: wait for given (or all running) workers to seal; returns verdicts and new bus messages.

Minimal example:

{
  "arguments": {},
  "name": "task_wait"
}

trace_path#

Who may call it: any seat

Purpose: Call graph around a symbol, with a confidence per edge.

Minimal example:

{
  "arguments": {
    "symbol": "..."
  },
  "name": "trace_path"
}

usage_status#

Who may call it: any seat

Purpose: Token spend and workspace telemetry by view. Content-free.

Minimal example:

{
  "arguments": {},
  "name": "usage_status"
}

verify_report#

Who may call it: any seat

Purpose: Worker: file verification evidence before finishing.

Minimal example:

{
  "arguments": {},
  "name": "verify_report"
}

verify_status#

Who may call it: any seat

Purpose: Read a session's verification report; with none, the caller's project, then the workspace.

Minimal example:

{
  "arguments": {},
  "name": "verify_status"
}

worktree_promote#

Who may call it: Chair-only

Purpose: Merge orch/<session> into base. Fail-closed, never pushes.

Minimal example:

{
  "arguments": {
    "session": "..."
  },
  "name": "worktree_promote"
}

worktree_prune#

Who may call it: Chair-only

Purpose: Prune orphan orch worktree dirs and orch/* branches.

Minimal example:

{
  "arguments": {},
  "name": "worktree_prune"
}

worktree_status#

Who may call it: Chair-only

Purpose: List this project's orch session worktrees (dirty/orphan).

Minimal example:

{
  "arguments": {},
  "name": "worktree_status"
}