Referencia de herramientas MCP

Cada herramienta MCP registrada: proposito, quien puede invocarla, parametros y un ejemplo minimo.

Referencia de herramientas MCP de orch

Generado por go run ./cmd/orch-docs desde mcp.ToolDefs() (client/internal/mcp/server.go) — el mismo manifiesto que sirve tools/list. 46 herramientas en total, 7 exclusivas del Chair (denyWorkerFanout, client/internal/mcp/spawn.go); cualquier otra herramienta puede invocarse desde cualquier asiento.

architecture#

Quien puede invocarla: cualquier asiento

Proposito: Directory-level map of the workspace: symbols per directory and edge counts between them. Read this before deciding where a change belongs.

parametro tipo obligatorio valor por defecto descripcion
session string no

Ejemplo minimo:

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

ask#

Quien puede invocarla: cualquier asiento

Proposito: 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.

parametro tipo obligatorio valor por defecto descripcion
context string no what you already know; keep it telegraphic
options array<string> no when given, the answer must be one of these
question string si
timeout_sec integer no default 600
to_project string no registered project id — ask that project's running Chair instead
to_session string no defaults to the running Chair of this project

Ejemplo minimo:

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

ask_answer#

Quien puede invocarla: cualquier asiento

Proposito: 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}.

parametro tipo obligatorio valor por defecto descripcion
answer string si
by string no
id integer si
symbol_ref object no points at the symbol that answers the question; must resolve under project, shared scope only (campos: line, path, project, symbol)

Ejemplo minimo:

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

ask_list#

Quien puede invocarla: cualquier asiento

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

parametro tipo obligatorio valor por defecto descripcion
limit integer no
session string no
status string no

Ejemplo minimo:

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

code_snippet#

Quien puede invocarla: cualquier asiento

Proposito: 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.

parametro tipo obligatorio valor por defecto descripcion
id string no numeric symbol id (alternative to symbol)
max_lines integer no default 120
project string no fetch from another registered project (shared scope only, unless it's your own project)
session string no
symbol string no symbol name

Ejemplo minimo:

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

context_crush#

Quien puede invocarla: cualquier asiento

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

parametro tipo obligatorio valor por defecto descripcion
text string si

Ejemplo minimo:

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

context_externalize#

Quien puede invocarla: cualquier asiento

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

parametro tipo obligatorio valor por defecto descripcion
text string si

Ejemplo minimo:

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

context_retrieve#

Quien puede invocarla: cualquier asiento

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

parametro tipo obligatorio valor por defecto descripcion
id string si

Ejemplo minimo:

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

Quien puede invocarla: cualquier asiento

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

parametro tipo obligatorio valor por defecto descripcion
limit integer no
query string si

Ejemplo minimo:

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

dispatch_worker#

Quien puede invocarla: solo Chair

Proposito: 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.

parametro tipo obligatorio valor por defecto descripcion
actor string no
agent string si worker agent id (codex, commandcode, …)
force boolean no
inplace boolean no
keep_worktree boolean no
name string no
project string no
prompt string si
session string no
timeout_sec integer no
title string no
wait boolean no block until the worker exits (default false: return as soon as it is running)

Ejemplo minimo:

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

entitlements_status#

Quien puede invocarla: cualquier asiento

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

Sin parametros.

Ejemplo minimo:

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

impact#

Quien puede invocarla: cualquier asiento

Proposito: 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.

parametro tipo obligatorio valor por defecto descripcion
git_range string no e.g. main...HEAD; ignored when paths is given
paths array<string> no
session string no

Ejemplo minimo:

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

inspect_symbol#

Quien puede invocarla: cualquier asiento

Proposito: Inspect a shared symbol by name or numeric id

parametro tipo obligatorio valor por defecto descripcion
name string si

Ejemplo minimo:

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

lock_acquire#

Quien puede invocarla: cualquier asiento

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

parametro tipo obligatorio valor por defecto descripcion
holder string si session id
path string si
ttl_min integer no

Ejemplo minimo:

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

lock_check#

Quien puede invocarla: cualquier asiento

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

parametro tipo obligatorio valor por defecto descripcion
holder string si
path string si

Ejemplo minimo:

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

lock_release#

Quien puede invocarla: cualquier asiento

Proposito: Release shared-path semaphore

parametro tipo obligatorio valor por defecto descripcion
holder string si
path string si

Ejemplo minimo:

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

lock_status#

Quien puede invocarla: cualquier asiento

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

parametro tipo obligatorio valor por defecto descripcion
path string no

Ejemplo minimo:

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

memory_conflicts#

Quien puede invocarla: cualquier asiento

Proposito: List active memories that share type+title but differ in body

Sin parametros.

Ejemplo minimo:

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

memory_export#

Quien puede invocarla: cualquier asiento

Proposito: Export the memory estate as OKF-lite markdown (v0.2-compatible)

parametro tipo obligatorio valor por defecto descripcion
all boolean no include expired/superseded
dir string no output dir (default memory.okf_dir)
limit integer no

Ejemplo minimo:

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

memory_forget#

Quien puede invocarla: cualquier asiento

Proposito: Soft-expire a memory by id

parametro tipo obligatorio valor por defecto descripcion
id string si

Ejemplo minimo:

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

memory_import#

Quien puede invocarla: cualquier asiento

Proposito: Import OKF-lite markdown files into the memory estate

parametro tipo obligatorio valor por defecto descripcion
dir string no input dir (default memory.okf_dir)

Ejemplo minimo:

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

memory_list#

Quien puede invocarla: cualquier asiento

Proposito: List active memories (optional type filter)

parametro tipo obligatorio valor por defecto descripcion
limit integer no
type string no

Ejemplo minimo:

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

memory_recall#

Quien puede invocarla: cualquier asiento

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

parametro tipo obligatorio valor por defecto descripcion
limit integer no
query string no
type string no

Ejemplo minimo:

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

memory_remember#

Quien puede invocarla: cualquier asiento

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

parametro tipo obligatorio valor por defecto descripcion
source string no
tags string no
text string si
title string no
type string no

Ejemplo minimo:

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

memory_sweep#

Quien puede invocarla: cualquier asiento

Proposito: Expire memories past retention_days (yaml or defaults)

Sin parametros.

Ejemplo minimo:

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

msg_ack#

Quien puede invocarla: cualquier asiento

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

parametro tipo obligatorio valor por defecto descripcion
agent string no
id integer si
session string no

Ejemplo minimo:

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

msg_inbox#

Quien puede invocarla: cualquier asiento

Proposito: 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)

parametro tipo obligatorio valor por defecto descripcion
agent string no
limit integer no
session string no
unread boolean no

Ejemplo minimo:

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

msg_peers#

Quien puede invocarla: cualquier asiento

Proposito: 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

parametro tipo obligatorio valor por defecto descripcion
session string no from-session → project family roster
to_project string no registered project id — peers under that project only
to_worker string no stable worker id → its current session

Ejemplo minimo:

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

msg_roster#

Quien puede invocarla: cualquier asiento

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

parametro tipo obligatorio valor por defecto descripcion
session string si

Ejemplo minimo:

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

msg_send#

Quien puede invocarla: cualquier asiento

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

parametro tipo obligatorio valor por defecto descripcion
body string si
from_agent string no
from_session string no
kind string no
name string no target name/session/agent when using to_role
parent_id integer no
payload_path string no
to_agent string no
to_project string no registered project id — routes to that project's running Chair
to_role string no parent|child|sibling
to_session string no
to_worker string no stable worker id; resolves to that worker's current session

Ejemplo minimo:

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

msg_stale#

Quien puede invocarla: cualquier asiento

Proposito: List unread alerts older than older_min minutes

parametro tipo obligatorio valor por defecto descripcion
older_min integer no

Ejemplo minimo:

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

search_shared_symbols#

Quien puede invocarla: cualquier asiento

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

parametro tipo obligatorio valor por defecto descripcion
limit integer no
project string no registered project id — only hits under that project's path
query string si

Ejemplo minimo:

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

task_add#

Quien puede invocarla: solo Chair

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

parametro tipo obligatorio valor por defecto descripcion
acceptance_criteria array<string> no each is shown to the worker and must come back met/not in its verification report
agent string no assignee agent id (e.g. codex, commandcode)
body string no task body / worker prompt
context string no standing background the worker needs (constraints, ownership, where the code lives)
ledger string no ledger item ref
title string si

Ejemplo minimo:

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

task_assign#

Quien puede invocarla: solo Chair

Proposito: Chair: assign task to an agent id

parametro tipo obligatorio valor por defecto descripcion
agent string si
id string si

Ejemplo minimo:

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

task_claim#

Quien puede invocarla: cualquier asiento

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

parametro tipo obligatorio valor por defecto descripcion
holder string si session id
item integer si checklist item number, e.g. 36 for "- [ ] 36."
ledger string si ledger file path, e.g. .workflow/LEDGER-R2.md
ttl_min integer no

Ejemplo minimo:

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

task_done#

Quien puede invocarla: cualquier asiento

Proposito: Mark task done or failed

parametro tipo obligatorio valor por defecto descripcion
id string si
status string no done|failed

Ejemplo minimo:

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

task_list#

Quien puede invocarla: cualquier asiento

Proposito: List chair tasks (optional status filter)

parametro tipo obligatorio valor por defecto descripcion
limit integer no
status string no open|assigned|running|done|failed

Ejemplo minimo:

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

task_release#

Quien puede invocarla: cualquier asiento

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

parametro tipo obligatorio valor por defecto descripcion
holder string si
item integer si
ledger string si

Ejemplo minimo:

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

task_run#

Quien puede invocarla: solo Chair

Proposito: 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.

parametro tipo obligatorio valor por defecto descripcion
actor string no
force boolean no bypass clarify_before_spawn ledger gate
id string si
inplace boolean no
keep_worktree boolean no
name string no
project string no
session string no
timeout_sec integer no
wait boolean no block until the worker exits (default false: return as soon as it is running)

Ejemplo minimo:

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

trace_path#

Quien puede invocarla: cualquier asiento

Proposito: 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.

parametro tipo obligatorio valor por defecto descripcion
depth integer no hops, 1-5 (default 2)
direction string no
session string no session id, for content-free usage measurement
symbol string si symbol name or numeric id

Ejemplo minimo:

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

usage_status#

Quien puede invocarla: cualquier asiento

Proposito: 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.

parametro tipo obligatorio valor por defecto descripcion
recent integer no summary view only: also return the N most recent attempts
view string no summary (default) | leaks | governance

Ejemplo minimo:

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

verify_report#

Quien puede invocarla: cualquier asiento

Proposito: 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.

parametro tipo obligatorio valor por defecto descripcion
criteria array<object> no
session string no defaults to ORCH_SESSION
summary string no one telegraphic line
symbols array<object> no
task string no defaults to ORCH_TASK
tests array<object> no

Ejemplo minimo:

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

verify_status#

Quien puede invocarla: cualquier asiento

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

parametro tipo obligatorio valor por defecto descripcion
session string no

Ejemplo minimo:

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

worktree_promote#

Quien puede invocarla: solo Chair

Proposito: Merge orch/<session> into base (fail-closed on conflicts; no auto-push)

parametro tipo obligatorio valor por defecto descripcion
base string no
project string no
session string si
strategy string no merge|rebase

Ejemplo minimo:

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

worktree_prune#

Quien puede invocarla: solo Chair

Proposito: Prune orphan orch worktree dirs and orch/* branches

parametro tipo obligatorio valor por defecto descripcion
project string no

Ejemplo minimo:

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

worktree_status#

Quien puede invocarla: solo Chair

Proposito: List orch session git worktrees (dirty/orphan) for the project

parametro tipo obligatorio valor por defecto descripcion
base string no base branch override
project string no

Ejemplo minimo:

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