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. 56 herramientas en total, 9 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 map: symbols and edges per directory.

parametro tipo obligatorio valor por defecto descripcion
limit integer no 20

Ejemplo minimo:

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

ask#

Quien puede invocarla: cualquier asiento

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

parametro tipo obligatorio valor por defecto descripcion
context string no
options array<string> no
question string si
timeout_sec integer no 600
to_project string no
to_session string no

Ejemplo minimo:

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

ask_answer#

Quien puede invocarla: cualquier asiento

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

parametro tipo obligatorio valor por defecto descripcion
answer string si
by string no
id integer si
symbol_ref object no (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 by status.

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

Ejemplo minimo:

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

code_snippet#

Quien puede invocarla: cualquier asiento

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

parametro tipo obligatorio valor por defecto descripcion
id string no
max_lines integer no 120
project string no
symbol string no

Ejemplo minimo:

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

context_crush#

Quien puede invocarla: cualquier asiento

Proposito: Crush repetitive success/log noise.

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: Park bulky text in `.orch/context`; returns a 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: Fetch a full externalized blob by id.

parametro tipo obligatorio valor por defecto descripcion
id string si

Ejemplo minimo:

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

Quien puede invocarla: cualquier asiento

Proposito: FTS over externalized context chunks.

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

Ejemplo minimo:

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

decision_get#

Quien puede invocarla: cualquier asiento

Proposito: Fetch Decision by id.

parametro tipo obligatorio valor por defecto descripcion
id string si

Ejemplo minimo:

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

decision_list#

Quien puede invocarla: cualquier asiento

Proposito: Pending HITL decisions.

parametro tipo obligatorio valor por defecto descripcion
limit integer no 50

Ejemplo minimo:

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

dispatch_worker#

Quien puede invocarla: solo Chair

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

parametro tipo obligatorio valor por defecto descripcion
acp_session string no
actor string no
agent string no empty + risk: roster row
auth string no account|gateway; empty: config default
base string no start ref
continue string no resume session
force object no
force_load string no
force_reason string no
gate_ok string no
inplace boolean no
keep_worktree boolean no
lane string no fast = small-fix lane
lesson_ok string no
model string no gateway model id
name string no
no_done_means boolean no
overlap_ok string no
plan boolean no read-only; returns a plan
plan_from string no earlier plan session to inject
project string no
prompt string no
risk string no security|money|keys: strong; ui|copy: cheap; agentless only
session string no
timeout_sec integer no
title string no
unknown_ok string no
wait boolean no

Ejemplo minimo:

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

entitlements_status#

Quien puede invocarla: cualquier asiento

Proposito: Active plan, quotas and capability catalog.

Sin parametros.

Ejemplo minimo:

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

evidence_bundle#

Quien puede invocarla: solo Chair

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

parametro tipo obligatorio valor por defecto descripcion
session string si

Ejemplo minimo:

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

impact#

Quien puede invocarla: cualquier asiento

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

parametro tipo obligatorio valor por defecto descripcion
git_range string no
limit integer no 20
paths array<string> no
symbol string no

Ejemplo minimo:

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

inspect_symbol#

Quien puede invocarla: cualquier asiento

Proposito: Inspect one shared symbol by name or 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: Take the shared/** semaphore before editing.

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

Ejemplo minimo:

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

lock_check#

Quien puede invocarla: cualquier asiento

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

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 a shared/** lock; reindexes and notifies peers.

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: One lock, or every held lock when path is 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: Memories sharing type+title but differing 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.

parametro tipo obligatorio valor por defecto descripcion
all boolean no
dir string no
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 into the memory estate.

parametro tipo obligatorio valor por defecto descripcion
dir string no

Ejemplo minimo:

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

memory_list#

Quien puede invocarla: cualquier asiento

Proposito: List active memories.

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

Ejemplo minimo:

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

memory_recall#

Quien puede invocarla: cualquier asiento

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

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

Ejemplo minimo:

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

memory_remember#

Quien puede invocarla: cualquier asiento

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

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

Ejemplo minimo:

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

memory_sweep#

Quien puede invocarla: cualquier asiento

Proposito: Expire memories past retention_days.

Sin parametros.

Ejemplo minimo:

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

msg_ack#

Quien puede invocarla: cualquier asiento

Proposito: Ack a message by id as its recipient.

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 this seat's inbox; a Chair also gets role mail. wait_sec blocks for mail instead of polling.

parametro tipo obligatorio valor por defecto descripcion
agent string no
limit integer no 20
session string no
unread boolean no true
verbose boolean no
wait_sec integer no

Ejemplo minimo:

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

msg_peers#

Quien puede invocarla: cualquier asiento

Proposito: Discoverable sessions; session gives the roster.

parametro tipo obligatorio valor por defecto descripcion
limit integer no 20
session string no
to_project string no
to_worker string no

Ejemplo (de las pruebas):

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#

Quien puede invocarla: cualquier asiento

Proposito: Send a bus message.

parametro tipo obligatorio valor por defecto descripcion
body string si
from_agent string no
from_session string no
kind string no
name string no
parent_id integer no
payload_path string no
to_agent string no
to_project string no
to_role string no
to_session string no
to_worker string no
wake boolean no if nobody answers to that seat name, re-dispatch it with this body as its prompt (plan/quota checked first)

Ejemplo minimo:

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

msg_stale#

Quien puede invocarla: cualquier asiento

Proposito: Unread alerts older than older_min minutes.

parametro tipo obligatorio valor por defecto descripcion
limit integer no 20
older_min integer no 15

Ejemplo minimo:

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

notify_events#

Quien puede invocarla: cualquier asiento

Proposito: Outbound event catalog (n8n/Zapier).

Sin parametros.

Ejemplo minimo:

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

search_shared_symbols#

Quien puede invocarla: cualquier asiento

Proposito: Search the shared symbol registry.

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

Ejemplo minimo:

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

seat_attach#

Quien puede invocarla: cualquier asiento

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

parametro tipo obligatorio valor por defecto descripcion
session string no

Ejemplo minimo:

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

seat_detach#

Quien puede invocarla: cualquier asiento

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

parametro tipo obligatorio valor por defecto descripcion
session string no

Ejemplo minimo:

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

seat_read#

Quien puede invocarla: cualquier asiento

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

parametro tipo obligatorio valor por defecto descripcion
deep boolean no
deep_timeout_sec integer no 15
lines integer no
session string no

Ejemplo minimo:

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

seat_report#

Quien puede invocarla: cualquier asiento

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

parametro tipo obligatorio valor por defecto descripcion
next string no
pid integer no
preset string no
resume_ref string no
session string no
state string si
summary string no

Ejemplo minimo:

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

seat_status#

Quien puede invocarla: cualquier asiento

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

parametro tipo obligatorio valor por defecto descripcion
session string no

Ejemplo minimo:

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

seat_wait#

Quien puede invocarla: cualquier asiento

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

parametro tipo obligatorio valor por defecto descripcion
session string no
timeout_sec integer no 30
until array<string> si

Ejemplo minimo:

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

task_add#

Quien puede invocarla: solo Chair

Proposito: Chair: create a Board task.

parametro tipo obligatorio valor por defecto descripcion
acceptance_criteria array<string> no
agent string no
body string no
context string no
ledger string no
role string no
title string si

Ejemplo minimo:

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

task_assign#

Quien puede invocarla: solo Chair

Proposito: Chair: assign a task to an agent.

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: Claim a ledger checklist item; fails if a live session holds it.

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

Ejemplo minimo:

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

task_done#

Quien puede invocarla: cualquier asiento

Proposito: Mark a task done or failed.

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

Ejemplo minimo:

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

task_list#

Quien puede invocarla: cualquier asiento

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

parametro tipo obligatorio valor por defecto descripcion
limit integer no 20
status string no
verbose boolean no

Ejemplo minimo:

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

task_release#

Quien puede invocarla: cualquier asiento

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

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: dispatch an assigned task as a worker. Async.

parametro tipo obligatorio valor por defecto descripcion
acp_session string no
actor string no
base string no
force object no
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

Ejemplo minimo:

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

task_wait#

Quien puede invocarla: solo Chair

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

parametro tipo obligatorio valor por defecto descripcion
all boolean no
sessions array<string> no
timeout_sec integer no 300

Ejemplo minimo:

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

trace_path#

Quien puede invocarla: cualquier asiento

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

parametro tipo obligatorio valor por defecto descripcion
depth integer no 2
direction string no "both"
limit integer no 20
symbol string si

Ejemplo minimo:

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

usage_status#

Quien puede invocarla: cualquier asiento

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

parametro tipo obligatorio valor por defecto descripcion
limit integer no 20
recent integer no
verbose boolean no
view string no "summary"

Ejemplo minimo:

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

verify_report#

Quien puede invocarla: cualquier asiento

Proposito: Worker: file verification evidence before finishing.

parametro tipo obligatorio valor por defecto descripcion
criteria array<object> no
session string no
summary string no
symbols array<object> no
task string no
tests array<object> no

Ejemplo minimo:

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

verify_status#

Quien puede invocarla: cualquier asiento

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

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, never pushes.

parametro tipo obligatorio valor por defecto descripcion
base string no
pr boolean no Push and open a PR with the evidence summary (needs gh; else skipped).
project string no
session string si
strategy string no

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 this project's `orch` session worktrees (dirty/orphan).

parametro tipo obligatorio valor por defecto descripcion
base string no
limit integer no 20
project string no

Ejemplo minimo:

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