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. 46 tools total, 7 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-level map of the workspace: symbols per directory and edge counts between them. Read this before deciding where a change belongs.

Minimal example:

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

ask#

Who may call it: any seat

Purpose: Worker: ask the Chair a blocking question and wait for the answer. Use when a decision is not yours to make; do not guess and do not spawn.

Minimal example:

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

ask_answer#

Who may call it: any seat

Purpose: Chair: answer a blocking ask by id; the worker unblocks immediately. For "how did you solve X" across projects, add symbol_ref instead of pasting code — the asker fetches it with code_snippet{project}.

Minimal example:

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

ask_list#

Who may call it: any seat

Purpose: Chair: list asks (status open|answered|timeout|all, default open)

Minimal example:

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

code_snippet#

Who may call it: any seat

Purpose: One symbol's body by line range instead of the whole file — the preferred read path for "show me how X works". Capped at max_lines.

Minimal example:

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

context_crush#

Who may call it: any seat

Purpose: Crush repetitive success/log noise (Headroom-like, in-house)

Minimal example:

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

context_externalize#

Who may call it: any seat

Purpose: Crush (if enabled) and externalize bulky text to .orch/context; returns stub + id

Minimal example:

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

context_retrieve#

Who may call it: any seat

Purpose: Retrieve full externalized context blob by id (CCR)

Minimal example:

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

context_search#

Who may call it: any seat

Purpose: FTS search over externalized context chunks (BM25-like)

Minimal example:

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

dispatch_worker#

Who may call it: Chair-only

Purpose: Chair (any BYO seat): one-shot spawn a worker via orch (agent id + prompt). Creates a Board task row. Async by default, so two workers can run side by side and review each other; the verdict arrives as a handoff message. Prefer when user says run a worker with orch — never open that CLI yourself.

Minimal example:

{
  "arguments": {
    "agent": "...",
    "prompt": "..."
  },
  "name": "dispatch_worker"
}

entitlements_status#

Who may call it: any seat

Purpose: Active plan, quotas, and capability catalog (allowed vs LOCKED with upgrade hints)

No parameters.

Minimal example:

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

impact#

Who may call it: any seat

Purpose: What a change reaches: symbols declared in the given paths plus their callers up to two hops. With no paths, uses the workspace's own git diff --name-only.

Minimal example:

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

inspect_symbol#

Who may call it: any seat

Purpose: Inspect a shared symbol by name or numeric id

Minimal example:

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

lock_acquire#

Who may call it: any seat

Purpose: Acquire shared-path semaphore before editing shared/**

Minimal example:

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

lock_check#

Who may call it: any seat

Purpose: Deny unless holder has a valid lock on shared/** path (enforce before edit)

Minimal example:

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

lock_release#

Who may call it: any seat

Purpose: Release shared-path semaphore

Minimal example:

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

lock_status#

Who may call it: any seat

Purpose: Status of one lock path, or list held locks if path empty

Minimal example:

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

memory_conflicts#

Who may call it: any seat

Purpose: List active memories that share type+title but differ 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 (v0.2-compatible)

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 files into the memory estate

Minimal example:

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

memory_list#

Who may call it: any seat

Purpose: List active memories (optional type filter)

Minimal example:

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

memory_recall#

Who may call it: any seat

Purpose: FTS recall of active memories (brief before reinventing)

Minimal example:

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

memory_remember#

Who may call it: any seat

Purpose: Store a durable typed memory in the local orch estate (decision/fact/preference/…)

Minimal example:

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

memory_sweep#

Who may call it: any seat

Purpose: Expire memories past retention_days (yaml or defaults)

No parameters.

Minimal example:

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

msg_ack#

Who may call it: any seat

Purpose: Ack a message as recipient (session and/or agent must match; session defaults like msg_inbox)

Minimal example:

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

msg_inbox#

Who may call it: any seat

Purpose: Read inbox for session and/or agent (session defaults to ORCH_SESSION, then to this Chair's own seat when orch mcp runs as a pure MCP-server Chair)

Minimal example:

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

msg_peers#

Who may call it: any seat

Purpose: List discoverable sessions; pass session for kinship roster, to_project for that project's peers, or to_worker to locate one worker's live session

Minimal example:

{
  "arguments": {},
  "name": "msg_peers"
}

msg_roster#

Who may call it: any seat

Purpose: Project family roster (parent/child/sibling) relative to session

Minimal example:

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

msg_send#

Who may call it: any seat

Purpose: Send disco note/handoff/alert; optional to_worker (stable worker id), to_role=parent|child|sibling (project kinship) or to_project= (that project's running Chair)

Minimal example:

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

msg_stale#

Who may call it: any seat

Purpose: List unread alerts older than older_min minutes

Minimal example:

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

search_shared_symbols#

Who may call it: any seat

Purpose: Search the shared symbol registry (FTS/LIKE); every hit carries the registered project it resolves under, if any

Minimal example:

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

task_add#

Who may call it: Chair-only

Purpose: Chair (any BYO seat): create a task (optional agent assignee). Prefer over shelling orch task add.

Minimal example:

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

task_assign#

Who may call it: Chair-only

Purpose: Chair: assign task to an agent id

Minimal example:

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

task_claim#

Who may call it: any seat

Purpose: Any seat: atomically claim one ledger checklist item ("- [ ] N.") via shared_locks; fails clearly if another live session holds it

Minimal example:

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

task_done#

Who may call it: any seat

Purpose: Mark task done or failed

Minimal example:

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

task_list#

Who may call it: any seat

Purpose: List chair tasks (optional status filter)

Minimal example:

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

task_release#

Who may call it: any seat

Purpose: Release a ledger item claim (holder must match, or holder=*)

Minimal example:

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

task_run#

Who may call it: Chair-only

Purpose: Chair (any BYO seat): dispatch an assigned task as a worker session (ledger-gated). Async by default — returns once the worker is running; the verdict arrives as a handoff message. Never spawn vendor CLIs outside orch.

Minimal example:

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

trace_path#

Who may call it: any seat

Purpose: Call graph around one symbol: who calls it, what it calls, with a confidence per edge (1.0 resolved by package or file, 0.7 by receiver type, 0.4 name heuristic). Prefer this over reading files to understand how code connects.

Minimal example:

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

usage_status#

Who may call it: any seat

Purpose: Token spend and crush savings for this workspace: by session, by worker, by model — or, with view, the same leak/governance telemetry orch usage --leaks/--governance print (rereads, repeats, oversized results, silent streaks; conflict/duplicate rate, cross-session file collisions). Content-free — the gateway ledger never stores prompts.

Minimal example:

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

verify_report#

Who may call it: any seat

Purpose: Worker: attach verification evidence to this session (tests run, shared symbols exported/reused, acceptance criteria met). Call before finishing; orch adds guardrails and touched files when the session closes.

Minimal example:

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

verify_status#

Who may call it: any seat

Purpose: Read the verification report for a session (defaults to ORCH_SESSION)

Minimal example:

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

worktree_promote#

Who may call it: Chair-only

Purpose: Merge orch/ into base (fail-closed on conflicts; no auto-push)

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 orch session git worktrees (dirty/orphan) for the project

Minimal example:

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