Tools Reference

BMO exposes dozens of built-in tools to the agent. Use options.disabled_tools to hide built-ins globally, [agents.<id>.tools] to shape one agent’s tool set, and [permissions].allowed_tools only to skip permission prompts for named tools.

How to use this reference

Reference provenance: manual_reference_debt — curated operator subset; runtime registries in internal/agent/tool_descriptors.go and internal/mcp/tools/catalog.go stay authoritative (docs/book/reference-provenance.json).

Use this page to answer two questions: which capability exists, and which boundary controls it. If a tool is missing in the TUI, check session mode, tool-gates, disabled tools, and permissions before assuming the implementation is absent.

Implementation drift check: when adding a tool, register it in internal/agent/tool_descriptors.go and add or extend a row in this reference (or open a follow-up to generate the table from the registry). Quick audit: rg 'Name: [a-z0-9_]+ToolName' internal/agent/tool_descriptors.go vs the tables below.

Discovering tools in the TUI

Command palette: press ctrl+p (or type /) and switch to the Tools tab to see the current tool set (after mode/tool-gate).
Chat: run /tools to browse the tool list, /capabilities for a compact summary, or /agent_kinds for the configured kind registry (see Agent kinds).

Live BMO TUI: the command palette Tools tab showing the current effective tool set after session mode, disabled_tools, and permissions narrow the registry — the surface to debug before assuming a tool is missing.

internal/agent/tool_descriptors.go is the canonical source for tool taxonomy. Tools tagged workflow are non-primitive; everything else defaults to primitive. Legacy multiplex tools that used the convenience tag are removed from the registry (use split primitives — see tools-workflows.md. Related composition primitives such as spawn_agent stay primitives. For when to use workflow-tagged tools vs composing primitives, see tools-workflows.md.

Tool gates and session modes are part of the tool contract. If a needed tool is blocked, treat that as a real boundary: switch to the smallest suitable mode and retry the blocked action rather than routing around the boundary with a broader tool.

sequenceDiagram
    autonumber
    participant Operator
    participant Palette as Command palette
    participant TUI as BMO TUI
    participant Registry as Tool registry
    participant Gates as Mode and policy gates
    participant Agent as Current agent
    Operator->>Palette: ctrl+p or /
    Palette->>TUI: request Tools tab
    TUI->>Registry: read registered tools and descriptors
    Registry-->>TUI: names, descriptions, tags, input hints
    TUI->>Gates: apply session mode, disabled_tools, permissions
    Gates-->>TUI: effective tool set and blocked reasons
    TUI-->>Palette: searchable tools list
    Operator->>Palette: filter or select tool
    Palette->>Agent: insert tool-aware prompt or action
    Agent->>Gates: propose tool call
    Gates-->>Agent: allow, ask approval, or refuse

stateDiagram-v2
    [*] --> Proposed: agent proposes tool call
    Proposed --> ModeGate: session mode allows tool?
    ModeGate --> Blocked: not in current mode
    ModeGate --> DisabledGate: allowed by mode
    DisabledGate --> Blocked: hidden by disabled_tools
    DisabledGate --> PermissionGate: available
    PermissionGate --> Waiting: needs operator approval
    PermissionGate --> Executing: pre-approved
    Waiting --> Executing: approved
    Waiting --> Refused: denied
    Executing --> Result: tool returns output
    Result --> [*]
    Blocked --> [*]
    Refused --> [*]

When a sidebar item has an active diagnostic intent, BMO routes clicks to the contextually appropriate dialog instead of the default action.

Sidebar Item	Active Intent	Dialog Opened
Provider health	Provider error/cooldown	Provider diagnostics
Protocols / MCP	Auth required	MCP connection dialog
Context lineage	Pruning/shedding active	Context lineage inspector
Run status	Run failed	Run result review

Visual hint: items with an active intent show ! prefix in their description.

File system

Tool	Description
`view`	Read a file’s contents, optionally with a line range
`glob`	Find files matching a glob pattern
`grep`	Search file contents with regex (ripgrep-backed)
`ls`	List directory contents
`fetch`	Read a local file path or URL
`download`	Download a remote URL to a local file

Editing

Tool	Description
`write`	Write or overwrite a file
`edit`	Apply a targeted string replacement in a file
`multiedit`	Apply multiple edits to one file sequentially
`apply_patch`	Apply a unified diff patch to the working tree
`delete_file`	Delete a file in the workspace (path must be within workspace; user approval required)

File history

Tool	Description
`list_file_history`	List file versions stored for a session (optionally filter by path)
`get_file_version`	Get content and metadata for a file version by ID or by session+path (latest)
`delete_file_version`	Delete a single file version from the session’s file history by ID (from list_file_history)

Checkpoints

Safety note: checkpoint undo operations can run git reset --hard against the repository. Inspect the target checkpoint and preserve any work you want to keep before confirming an undo.

The agent registry exposes the checkpoint_* verbs below for the session checkpoint store.

Tool	Description
`checkpoint_create`	Create a named session checkpoint for the current or specified session
`checkpoint_list`	List saved session checkpoints for the current or specified session
`checkpoint_get`	Fetch one saved session checkpoint by ID
`checkpoint_update`	Rename an existing session checkpoint
`checkpoint_restore`	Restore a session to a saved checkpoint
`checkpoint_delete`	Delete a saved session checkpoint
`checkpoint_undo`	Rewind the last git commit(s) with `git reset --hard HEAD~N`; intended for checkpoint recovery, defaults to 1 step, and requires `confirm: true`

Run lifecycle

Tool	Description
`cancel_run`	Cancel the current session run or a specific session’s run
`list_agent_runs`	List persisted agent runs from the durable run ledger. Optional `session_id` filters a single row’s `session_id`; optional `family_session_id` returns parent and child run rows in one list (`session_id` or `parent_session_id` match — same idea as `/debugger` and `GET /v1/agent-runs?family_session_id=…`). If both are set, `family_session_id` wins for the session filter. MCP: `bmo_list_agent_runs` (opt-in via `exposed_tools`) returns the same JSON as `GET /v1/agent-runs` (full run records).
`get_session_phases`	Read the latest persisted per-turn phase timeline for a session (same source as TUI gloss). This is not a live process list; for in-flight coordination signals see the TUI Activity row when enabled. Integrators: `/gloss` is a view over this ledger—prefer `get_session_phases`, `get_agent_run`, and `get_agent_run_events` for automation rather than parsing gloss output.
`get_agent_run_events`	List ordered events for one persisted agent run (includes bash runtime seam kinds `sandbox_exec_started`, `local_shell_started`, `background_job_started` when recorded, alongside `phases`, tools, etc.)
`get_agent_run`	Get one persisted agent run plus derived artifacts
`update_agent_run`	Update a persisted agent run by `run_id`; currently supports `action: "cancel"` for active runs
`fork_agent_run`	Fork a run at a checkpoint-backed step into a new branch session
`delete_agent_run`	Delete a persisted agent run and its events from the ledger

Ledger bootstrap: Durable run rows need a data directory with bmo.db and a configured run store (normal bmo / HTTP service / autopilot service app with SQLite). The OpenAI-compat ledger path additionally requires [options.openai_compat]. When the store is not configured, list/get return errors consistent with the topic. See Durable run ledger.

Execution

Tool	Description
`bash`	Run a shell command and return output

Background jobs

Tool	Description
`job_output`	Read output from a running background bash job
`job_kill`	Terminate a background bash job
`job_list`	List active and recent background bash jobs

Test runner

Tool	Description
`run_tests`	Run Go tests via `go test -json` and return structured pass/fail/skip results, elapsed time, failure text, and command metadata

Process lifecycle

Status/inspection tools are available so agents can understand host runtime state. Mutating process-lifecycle tools are high-risk and default off: set BMO_ENABLE_PROCESS_LIFECYCLE_TOOLS in the BMO process environment to register them.

Tool	Availability	Description
`daemon_status`	Default	Inspect daemon runtime status, including spawned-child audit posture and residue
`autopilot_status`	Default	Inspect autopilot runtime status: posture, pillars, PID files, manifest, and recent `autopilot.fired` events
`daemon_restart`	`BMO_ENABLE_PROCESS_LIFECYCLE_TOOLS`	Restart the managed daemon process
`autopilot_up`	`BMO_ENABLE_PROCESS_LIFECYCLE_TOOLS`	Start the long-lived autopilot/server process
`autopilot_down`	`BMO_ENABLE_PROCESS_LIFECYCLE_TOOLS`	Stop the long-lived autopilot/server process

Configuration

Config mutation is split across dedicated primitive tools (the former multiplexed config tool no longer exists as a single runtime tool); use the specific primitive for each action.

Tool	Description
`get_config`	Sanitized raw config inventory; use `get_config_status` for layered-config posture and `get_config_field_provenance` / `bmo config explain` for field provenance
`config_check`	Check whether a curated config key is set
`config_list`	List all curated config keys with current values
`config_get`	Read one curated value from the user config file; use `get_config_field_provenance` for the live snapshot value and applied rendering value
`get_config_field_provenance`	Return the live snapshot value for one bounded config field such as `options.tui.theme`, with load-time source provenance when it still matches the snapshot
`config_set`	Set a curated config value
`config_unset`	Unset a curated config key (restore default)
`config_reload`	Reload config from disk; active agent runs defer the apply and the shared status family records the bounded deferred/applied/failed aftermath
`config_update_providers`	Refresh provider metadata
`config_status`	Compatibility text-line summary for existing agents; prefer `get_config_status` for the structured layered-config snapshot with bounded mutation/reload truth
`get_config_status`	Structured layered-config status shared with `bmo config show-config-status`, `/config-status`, `GET /v1/config-status`, and MCP; includes loaded-layer posture, bounded effective-field highlights, process-bounded write-target resolution, and reload aftermath on live surfaces
`get_provider_auth_wizard`	Provider OAuth bootstrap status and `bmo auth <platform>` commands (TUI: Manage Providers)

Discovery and Observability

Tool	Description
`get_dirs`	Return the current working directory, data directory, and loaded config path/dir
`list_projects`	List tracked BMO projects from the shared global projects registry (same data as `bmo projects --json`)
`logs_report`	Return structured log entries from the current project’s `bmo.log` file
`stats_report`	Return the same usage and audit stats JSON as `bmo stats --json`
`capabilities`	Return BMO’s short in-chat capability summary
`list_agent_kinds`	List configured agent kinds from effective merged config (prompt id, mesh capability tags, explicit allowlist counts)—registry scope, not the same as `capabilities`
`list_tool_capabilities`	List the currently allowed tools for the active agent (name + description)
`list_models`	List configured models and availability from the current config
`runtime_features`	List runtime feature flags and availability details from the current instance
`session_observability`	Read the session-summary member of the run-observability family for one session family: bounded recent run usage, token/cost totals, performance, interruptibility, and adaptive decision trace parity (same JSON as `GET /v1/sessions/{id}/observability` when the HTTP or autopilot service has wired the HTTP server; optional `recent_runs_limit` matches the HTTP query param)
`run_ledger_status`	Read the live attached run-ledger posture snapshot: durable `agent_runs` availability, OpenAI-compat ledger state, bounded reconciliation state, ring capacity, histogram, and recent metadata-only telemetry (same live JSON as `GET /v1/run-ledger/posture` and MCP `bmo_get_run_ledger_status`; `bmo config show-run-ledger --format=json` shares the schema but reports `source=detached_projection`)
`list_recent_run_ledger_events`	Export the raw bounded `run_ledger.*` ring as JSON (capacity, saturation, returned count, and metadata-only events). Use this for machine-readable recent telemetry; use `list_agent_runs` / `get_agent_run_events` for durable row or event history.
`run_cue_ledger`	Read the cue-oriented member of the run-observability family for one session family: active actors, cue state, expected next action, expected evidence, and recovery controls (same JSON family as `GET /v1/sessions/{id}/run-cue-ledger`)
`inspect_run_trace`	Read the trace-lens member of the run-observability family for one run in the current session family: ordered tool-call-only events, outcome, and duration metadata (same JSON as `GET /v1/agent-runs/{run_id}/trace` when the caller supplies or inherits session scope; use `get_agent_run_events` for the broader event stream)
`session_diagnose`	Context-budget and resume-health breakdown for one session (same JSON as `bmo session diagnose --format=json`; MCP parity: `bmo_session_diagnose` when listed in `services.mcp.exposed_tools`)
`workspace_snapshot`	Return the current workspace environment snapshot, including observer slices, optional heat-map hints, and optional `environment_fields` (`v2`: linear TTL–decayed marker intensity, optional half-life via `bmo_field_half_life_seconds` on `leave_marker` payloads, optional global session/path depositions, optional `bmo_field_weight_permille`) when `[options.workspace_environment_fields]` is enabled
`workspace_claim`	T1 session path claims (and T2 shared path mirror when durable hard claims enabled): acquire, renew, release, list, or negotiate path-scoped claims. Soft claims are advisory; hard claims block overlapping mutation tools from other sessions until release, yield, expiry, or negotiation. Hard claims mirror to SQLite `workspace_path` rows for sibling BMO processes when durable mode is on.
`leave_marker`	Create, list, or delete workspace stigmergy markers used for handoffs and warnings
`fleet_regulation_status`	Return bounded fleet-regulation aggregates and the current recommendation/proposal state
`quality_gates_posture`	Read metadata-only Quality Gates posture: armed surfaces, actions, judge model status, fail-open/fail-block policy, and recent decision counts
`get_adaptive_orchestration`	Read adaptive orchestration parity JSON for the session (same payload as MCP `bmo_get_adaptive_orchestration`; requires `options.adaptive_orchestration.enabled`)
`get_teams_status`	Read the Teams orchestration posture snapshot: enabled state, counts, remote/daemon posture, config snapshot, and recent metadata-safe team events.
`get_journal_posture`	Read live in-process Journal posture: partition binding, action/outcome histogram, ring capacity, and recent metadata-only journal telemetry.
`get_journal`	Read the cross-subsystem dated journal narrative for a session, matching `/journal`, `bmo_get_journal`, `GET /v1/sessions/{id}/journal`, and `bmo config show-journal-narrative`.
`get_enforcement_status`	Read enforcement substrate posture: enabled state, active primitives, workspace claims, explicit zone modes, and recent metadata-only enforcement telemetry.
`get_mesh_status`	Read Agent Mesh posture: enabled state, registry URL, allowed capabilities, outcome/niche routing posture, daemon hints, and recent mesh telemetry.
`get_a2a_status`	Read A2A protocol posture: enabled state, agent name, card URL, HTTP listen state, daemon hints, and recent A2A telemetry.
`get_flow_awareness_status`	Read flow-awareness posture: effective config and recent metadata-only flow-awareness events. Use `list_recent_flow_awareness_events` for the raw ring only; full dev-timeline bodies remain prompt-only.
`get_apply_patch_status`	Read live apply-patch/smart-apply posture: sandbox mode, smart-apply config, action histogram, and recent apply-patch telemetry.
`get_prompt_stack_status`	Read prompt-stack posture: ring capacity, recorded build count, and recent metadata-only prompt-stack builds.
`list_recent_prompt_stack_builds`	Export strict recent prompt-stack build metadata for agent workflows (metadata-only; no full prompt bodies).
`get_runtime_incident_status`	Read bounded runtime incident triage posture: aggregate counts, latest capsule metadata, and filter posture without listing every incident.
`get_ripple_status`	Read ripple-edits posture: suggested-edits mode, ripple caps, LSP client availability, and recent ripple events.
`get_file_tools_status`	Read file-tool telemetry posture: ring capacity, action histogram, and recent file-tool events.
`get_loop_detection_status`	Read loop-detection posture: effective config, recent bounded loop evidence, and operator-facing status hints.
`get_spawn_status`	Read the shared spawn-pool posture snapshot: pool limits plus live containment signals such as queue depth, breaker state, drain mode, held slots, recent children, and shutdown residue when runtime was observed.
`get_edit_capsules_status`	Read edit-capsule posture: enablement, ring capacity, and recent edit-capsule events.
`get_repo_preflight_status`	Read dry contract-preflight posture: matched contract surfaces and suggested command matrix without running checks.
`get_alerts_status`	Read operator-alert feed posture: ring capacity and recent operator-facing alerts.
`get_length_recovery_status`	Read the shared length-recovery status family: summarization enablement, continuation cap, streaming-compaction posture, and bounded recent recovery outcomes for the max-output, prompt-budget preflight, and provider-context overflow lanes.
`get_composition_graph`	Read the config-derived composition graph advisory JSON, matching `/composition_graph`, `bmo_get_composition_graph`, `GET /v1/sessions/{id}/composition-graph`, and `bmo config show-composition-graph`.
`get_compaction_reactions`	Read bounded idle-gate compaction telemetry for the session. When streaming session compaction has emitted semantic quality-gate metadata, this surface may include that metadata as an adjunct readout. This is the `/compaction` inspector source (`/compaction-reactions` slash alias), not the full session-compaction contract; use `describe_context` or `bmo session status` for the broader session-compaction posture.
`sandbox_status`	Read the sandbox execution posture without starting Docker, dialing SSH, invoking BuildKit, or running a command: command-execution backend, direct/staged file-write mode, background-shell support, validation-lane summary, and the bounded metadata-only `sandbox.*` ring (same read model as `bmo config show-sandbox` and the TUI `/sandbox` slash).
`get_finding_lifecycle_status`	Read the full finding-lifecycle status snapshot — ingest counters and the bounded recent-events ring in one call (same data as `bmo config show-finding-lifecycle` and the TUI `/findings` slash). Optional permissive `session_id` filter; the ring carries metadata only.
`list_recent_finding_lifecycle_events`	Read the strict per-session view of recent finding-lifecycle ring events (metadata-only). Pair with `get_finding_lifecycle_status` for ingest counters and the permissive sidebar view.
`describe_context`	Read a panoramic context snapshot for the session: token budget, effective pruning flags, memory configuration, compaction-reaction summary, shared session-compaction posture, and `codebase_context` counts/status (same source as the TUI `/context` hub). Optional `refresh_codebase_context: true` runs an auxiliary snapshot walk subject to `options.codebase_context.min_refresh_interval_seconds`
`eval_shadow_summary`	Return the bounded eval-shadow posture summary across recent runs, scorecards, latest timestamps, and proposal state so prompt and orchestration changes are measurable without enumerating raw artifacts. See Eval shadow summary and Shadow Evals.

Operating packs

Requires options.operating_packs = true in config and a session pack controller. Parity for the read-only JSON snapshot is documented in Operating mode parity.

Tool	Description
`session_set_pack`	Activate an operating pack for the current session (preset id from `options.operating_mode_presets` or pack name/path). HTTP parity: `POST /v1/session-operating-mode` (Bearer auth; same fields as tool JSON).
`session_clear_pack`	Clear the active operating pack for the session. HTTP parity: `DELETE /v1/session-operating-mode?session_id=…`.
`session_list_packs`	List discoverable operating packs for the workspace
`session_get_active_pack`	Return details for the session’s active pack, if any
`get_operating_mode`	Return redacted posture JSON: `session_id`, `enabled`, `state`, `active_operating_pack`, `operating_mode_preset_id`, optional `pack_manifest_path`, diagnostics, and active-pack counts (same object as `GET /v1/session-operating-mode` and MCP `bmo_get_operating_mode`)

Planning and workflow

Tool	Description
`init_project`	Run the project initialization flow that discovers context, loads instructions, and marks the project initialized
`set_plan_artifact`	Store or update the staged-workflow plan artifact (markdown); advance to execute with /approve in the TUI or `approve_plan`
`get_workflow_phase`	Read the current staged-workflow phase and approval-pending state
`get_staged_workflow_status`	View the bounded staged-workflow session posture
`approve_plan`	Approve the staged plan and move the session to execute phase (same as TUI /approve)
`return_to_plan`	Move a staged workflow back to the planning phase
`get_plan`	Read the currently stored plan artifact
`clear_plan`	Remove the stored plan artifact
`todos`	Create or replace the full session-local structured task list; not for Markdown checkboxes or workstream findings
`list_todos`	Read the current session-local structured task list without modifying it
`add_todo`	Append one session-local structured task item; not for Markdown checkboxes or workstream findings
`update_todo`	Update one session-local structured task item by 0-based index from `list_todos`
`delete_todo`	Remove one session-local structured task item by 0-based index from `list_todos`
`run_recipe`	Execute one recipe YAML as a workflow run
`recipe_list`	List available recipes
`recipe_validate`	Validate a recipe without running it
`schedule_create`	Create a scheduled recipe job
`schedule_list`	List all scheduled recipe jobs
`schedule_run_now`	Run a scheduled job immediately
`schedule_pause`	Pause a scheduled job
`schedule_unpause`	Unpause a scheduled job
`schedule_delete`	Delete a scheduled job
`schedule_update`	Update an existing scheduled job
`schedule_inspect`	Inspect a single scheduled job (details and running state)
`schedule_runs`	List run history for a scheduled job
`schedule_run_content`	Get output/content of a run by run ID
`get_scheduler_status`	View scheduler posture
`get_provider_status`	View provider-management posture and latest lifecycle summaries
`contract_rerun`	Re-run change-contract validations for the current work
`contract_list_obligations`	List outstanding change-contract obligations
`contract_waive_obligation`	Waive one change-contract obligation by ID
`analyze_ripple_impact`	Best-effort follow-up edits in other files after a change (ripple/LSP-backed); registered tool name (implementation file `suggest_next_edits.go`)
`summarize_session`	Trigger session compaction on demand by summarizing session history into a compact continuity artifact. This is part of the active-session recovery path, not the idle-gated background compaction executor.
`spawn_worktree_override`	Read or change the session-level next-spawn worktree and auto-remove override

Staging / review

Tool	Description
`staged_list`	List staged file changes awaiting acceptance
`staged_accept`	Accept one staged change
`staged_reject`	Reject one staged change
`staged_accept_all`	Accept all staged changes in the current batch

PTY / interactive

Tool	Description
`pty_spawn`	Spawn a full pseudo-terminal process (interactive shells, REPLs, etc.)
`pty_read`	Read output from a running PTY session
`pty_write`	Send input to a PTY session
`pty_kill`	Terminate a PTY session
`pty_list`	List all active PTY sessions
`pty_cleanup`	Clean up finished or stale PTY sessions

Web and research

Tool	Description
`web_fetch`	Fetch a URL and return the page content as markdown or HTML
`web_search`	Search the web and return results
`agentic_fetch`	Multi-step fetch chain for complex web research
`sourcegraph`	Search public repositories with Sourcegraph’s code search API

Embeddings and code search

Tool	Description
`semantic_search`	Search the codebase semantically using natural language queries instead of literal text patterns
`find_similar_code`	Find code chunks that are semantically similar to code at a specific file and line, enabling clone detection and refactoring discovery

Memory

Tool	Description
`memory_store`	Save a fact, decision, or convention to persistent memory
`memory_search`	Search stored memories; semantic when vector indexing is enabled, keyword-based otherwise
`memory_list`	List recent memories in a scope (`project`, `user`, or `local`)
`memory_get`	Get a single memory by ID and scope (same as GET /v1/memory/{id})
`memory_update`	Update a memory’s content by ID and scope
`memory_forget`	Delete a memory by scope and ID
`memory_projection_list`	List memory projections
`memory_projection_create`	Create a memory projection
`get_memory_projection`	Read one projection’s status and metadata
`memory_projection_set_read` / `memory_projection_set_write` / `memory_projection_rebuild` / `memory_projection_retry` / `memory_projection_retire` / `memory_projection_delete` / `memory_projection_rollback_read`	Projection lifecycle primitives (when memory projections enabled)

MCP resources

Tool	Description
`list_mcp_prompts`	List available prompts from a connected MCP server (read-only; server-owned)
`get_mcp_prompt`	Render an MCP prompt with arguments and return the prompt text (read-only; server-owned)
`list_mcp_resources`	List available resources from connected MCP servers (read-only; server-owned)
`read_mcp_resource`	Read a specific resource from an MCP server (read-only; server-owned)
`mcp_list_roots`	List current MCP root overrides per server (same as GET /v1/mcp/roots)
`get_mcp_root`	Get the active roots for one MCP server
`mcp_create_root`	Add one filesystem root to an MCP server without replacing the rest
`mcp_update_root`	Replace one existing MCP root with a new filesystem path
`mcp_delete_root`	Remove one filesystem root from an MCP server without clearing the whole override
`mcp_update_roots`	Set filesystem roots for an MCP server (same as PUT /v1/mcp/roots/{serverName})
`mcp_clear_roots`	Clear a persisted MCP root override for one server
`mcp_resolve_elicitation`	Answer an MCP server’s pending elicitation request

MCP server management (runtime)

Tool	Description
`mcp_register_server`	Register or replace a session-scoped runtime MCP server entry (not persisted; may require user approval)
`mcp_update_server`	Update fields on a session-scoped runtime MCP server entry (not persisted)
`mcp_unregister_server`	Remove a session-scoped runtime MCP server entry (not persisted)
`mcp_get_server`	Read one server block (redacted where appropriate)
`list_mcp_servers`	List configured MCP servers and connection metadata

Multi-agent

Tool	Description
`agent`	Run a child task agent with its default tool set
`custom_agent_list`	List custom agents from disk
`get_custom_agent`	Load one custom agent by name (metadata and instructions)
`create_custom_agent`	Create a new custom agent definition on disk (mutates config data; may require approval)
`update_custom_agent`	Update an existing custom agent definition
`delete_custom_agent`	Delete a custom agent definition file
`custom_agent_run`	Queue a custom agent into the current session by name
`spawn_agent`	Spawn a child agent with a prompt and scoped tool set
`wait_agent`	Block until a child agent completes; stream or collect output
`send_input`	Inject a follow-up message into a running child agent
`get_agent_output`	Read partial or final output without blocking
`close_agent`	Terminate a child agent and release its resources
`list_agents`	List all active child agents with their status (includes `spawned_by` + `explain` when available)
`spawn_agents_on_csv`	Fan out agents over CSV rows; each row becomes an isolated job
`report_agent_job_result`	Report one worker result back to a CSV fan-out batch
`create_team`	Provision a named team of persistent, goal-oriented sub-agents
`mesh_resolve`	Resolve agents by capability; returns candidate `node_id` and display `name` to help build an explicit `create_team` roster (requires mesh)
`decompose_task`	Break a goal into subtasks before or during team creation
`team_task_create`	Add a task to an existing team
`team_task_list`	List tasks for a team
`team_task_get`	Get one task from a team
`team_task_update`	Claim, run, complete, or fail a team task
`team_task_delete`	Delete one task from a team
`team_message_send`	Send a direct message to a teammate
`team_message_list`	Read queued unread team messages
`team_message_get`	Read one team message
`team_events`	Stream or list team lifecycle events
`team_broadcast`	Send the same message to all teammates
`team_shutdown`	Shut down a running team and collect task status
`list_teams`	List known teams
`get_team`	Get one team and its metadata
`delete_team`	Delete a persisted team
`team_cleanup`	Remove stale team state and cached resources
`team_update`	Update editable team metadata
`team_package_pull`	Pull one OCI team package into the cache (same as CLI `bmo team package pull`).
`team_package_list`	List cached team packages (same as CLI `bmo team package list`).
`team_package_remove`	Remove one cached team package (same as CLI `bmo team package remove`).
`team_package_update`	Refresh a cached team package (same as CLI `bmo team package update`).

Sessions and messages

In the TUI, ctrl+enter or /enqueue queues user text for the turn after the current run completes. The queue_enqueue tool uses the same coordinator queue (not the same contract as send_message, which injects into the transcript with permission flow). Technical detail: prompt-queue-parity.md.

Tool	Description
`create_session`	Create a new session
`switch_session`	Switch the active session
`list_sessions`	List known sessions
`get_session`	Read one session’s metadata
`update_session`	Update editable session metadata
`delete_session`	Delete a session
`send_message`	Inject a user message into the current or a specified session. Content is persisted as given; for maintained review prompts, use `view` on the workspace-root prompt corpus (maintainer artifact outside this repository from `agent-cli/bmo/`, applied from a maintainer workspace checkout outside this repository.
`get_message`	Get one message by ID
`list_messages`	List messages in the current session
`session_search`	Search prior session transcripts or list recent sessions
`update_message`	Update editable message fields
`delete_message`	Delete a message
`get_prompt_queue_status`	Inspect the current queued-prompt state
`queue_enqueue`	Enqueue a prompt to run after the current turn completes (TUI ctrl+enter / `/enqueue` parity)
`clear_prompt_queue`	Clear queued prompts waiting to run
`describe_hooks`	Describe currently configured session hooks

Operations

Tool	Description
`operations_create_deploy`	Create a deploy operation
`operations_create_promote`	Create a promote operation
`operations_create_rollback`	Create a rollback operation
`operations_create_infra_claim`	Create an infra-claim operation
`operations_approve`	Approve a pending operation
`operations_deny`	Deny a pending operation
`operations_expire`	Expire a pending operation
`operations_complete`	Mark an operation as completed
`operations_fail`	Mark an operation as failed
`operations_delete`	Delete an operation

Edit capsules

Requires options.edit_capsules = true and a wired edit-capsule service. HTTP list/create/update/delete for capsules is documented under Edit capsules (HTTP) (GET reads follow the shared bound-session contract; POST starts a capsule only and does not mirror the full create_edit_capsule tool flow).

Tool	Description
`delete_edit_capsule`	Delete an edit capsule by ID

Recipes, skills, and worktrees

Tool	Description
`list_skills`	List available Agent Skills from configured skill paths
`read_skill`	Read one skill document by name
`get_recipe`	Read one recipe by name
`list_worktrees`	List managed git worktrees
`worktree_get`	Get one worktree and its metadata
`worktree_create`	Create a managed git worktree
`worktree_update`	Update editable worktree metadata
`worktree_remove`	Remove one managed git worktree
`worktree_prune`	Prune stale managed worktrees

Operator questions

Unified pending prompts (tool permissions, MCP elicitations, agent clarifications). Same model as the TUI /questions command; see Operator questions.

Tool	Description
`list_pending_questions`	List pending questions (optional session / scope filters)
`get_question`	Fetch one question by id
`resolve_question`	Resolve a question (grant/deny/answer depending on source)
`ask_question`	Create an agent clarification prompt (when enabled)

Permissions and checkpoints

Tool	Description
`list_pending_permissions`	List permission requests awaiting a user decision
`permission_grant`	Approve a pending permission request
`permission_deny`	Deny a pending permission request
`checkpoint_create`	Create a session checkpoint
`checkpoint_list`	List available checkpoints
`checkpoint_get`	Read one checkpoint
`checkpoint_update`	Update editable checkpoint metadata
`checkpoint_restore`	Restore a checkpoint-backed branch or session state
`checkpoint_delete`	Delete a checkpoint

Model and session settings

Tool	Description
`session_mode`	Read or mutate the shared session-mode status family: current mode, reachable modes, deferred mode-change posture, and the latest bounded autoselect/manual-override fact for the session
`get_session_posture_status`	Read the canonical session-posture status family: desired posture genome, committed choreography state, pending transition conditions, and operator lock status
`set_session_model`	Switch the current session to a configured model
`set_reasoning_effort`	Update the current model’s reasoning-effort setting when supported

Workflow-tagged tools (`internal/agent/tool_descriptors.go`)

These tools are tagged workflow in the registry (multi-step or bundled behavior). Everything else defaults to primitive. Multiplex tools such as contract_obligations, fleet_policy, legacy workflow_checkpoint, daemon_control, autopilot_control, and memory_projection_update are not registered; use the split primitives listed in the split-primitives section.

Tool	Description
`agent`	Run a child task agent with its default tool set.
`spawn_agents_on_csv`	Fan out agents over CSV rows; each row becomes an isolated job.
`agentic_fetch`	Multi-step fetch chain for complex web research.
`create_team`	One-call team formation from an explicit teammate roster: team record, spawned teammates, optional preloaded subtasks (primitive alternative: `mesh_resolve` + `decompose_task` + `team_create` + `spawn_agent` + `team_task_create`).
`arena_workflow_list` / `arena_workflow_start` / `arena_workflow_status` / `arena_workflow_update` / `arena_workflow_accept` / `arena_workflow_delete`	Arena workflow tool family (multi-step arena run lifecycle).
`workflow_define` / `workflow_start` / `workflow_checkpoint`	Unified v2 workflow tool family for defining, starting, and checkpointing multi-step workflows.
`execute_dag`	Execute a validated A2A DAG with checkpoint support.
`orchestrate_workflow`	Execute a DAG of A2A invocations with checkpoint support.
`deploy_agent`	Build, push, and deploy an agent image (multi-step deploy workflow).
`deploy_fleet`	Deploy multiple agents from a fleet specification (multi-step fleet deploy workflow).

Staged workflow uses set_plan_artifact, get_workflow_phase, get_plan, clear_plan, return_to_plan, and approve_plan (all primitive in the registry). There is no submit_plan tool; approve with /approve or approve_plan.

Bundled pipelines (primitive taxonomy, multi-step runtime): run_recipe and summarize_session are primitive in registry taxonomy but internally run multi-step pipelines (RegistryRuntimeShapeBundledPipeline). They are not tagged workflow.

Common primitives near workflows: init_project, decompose_task, contract_rerun, contract_list_obligations, contract_waive_obligation, get_config, get_config_status, get_config_field_provenance, mcp_reconcile_tools, analyze_ripple_impact, spawn_agent, mesh_resolve, workflow_checkpoint_*, fleet_policy_*, memory_projection_*, get_memory_projection, daemon_status, autopilot_status.

Workflow-tools inspect family: Use bmo config show-workflow-tools for the config-only grouped view, /workflow-tools for the live TUI report, get_workflow_tools_status for the agent-native JSON surface, GET /v1/workflow-tools for HTTP, and bmo_get_workflow_tools_status for MCP. The shared snapshot keeps workflow-tagged tools, bundled-pipeline primitives, and staged-workflow controls separate with bounded availability reasons.

Primitive-tools inspect family: Use bmo config show-primitive-tools for the config-only grouped view, /primitive-tools for the TUI grouped report, get_primitive_tools_status for the agent-native JSON surface, GET /v1/primitive-tools for HTTP, and bmo_get_primitive_tools_status for MCP. The shared snapshot keeps direct single-action primitives, bundled-pipeline primitives, and gated/runtime-sensitive primitives separate, and includes bounded recent primitive-family activity from the shared execution boundary.

See tools-workflows.md for rationale and plan-phase details.

Deploy

Tool	Description
`deploy_agent`	Build, push, and deploy an agent image (workflow)
`deploy_fleet`	Deploy multiple agents from a fleet specification (workflow)
`create_fleet`	Declare one or more remote agents in the fleet registry without deploying them
`list_deployed_agents`	List all deployed agents and their status
`deployed_agent_inspect`	Inspect one deployed agent by name or ID
`deployed_agent_connect`	Connect to a deployed agent’s runtime
`deployed_agent_stop`	Stop a running deployed agent
`deployed_agent_remove`	Remove a deployed agent from the registry
`deployed_agent_delete`	Delete a deployed agent and its resources

Plugins

Tool	Description
`plugin_list`	List installed plugins from the shared plugin directory
`plugin_install`	Install a plugin from a git repository or local git checkout (approval required)
`plugin_update`	Pull the latest version of an installed plugin (approval required)
`plugin_remove`	Remove an installed plugin from the shared plugin directory (approval required)

Agent-to-Agent

Tool	Description
`invoke_a2a`	Delegate to a remote A2A agent: `agent_card_url`, deployed `agent_name`, or `capability` (mesh resolve + invoke; multi-candidate transport fallback). Continues via `task_id` / `context_id`. See A2A.
`delete_a2a_task`	Delete an A2A task by ID
`execute_dag`	Execute a validated A2A DAG with checkpoint support
`orchestrate_workflow`	Execute a DAG of A2A agent invocations with dependency tracking, parallel fanout, and template interpolation
`save_workflow_template`	Save a named DAG workflow template for later reuse
`list_workflow_templates`	List saved DAG workflow templates
`get_workflow_template`	Load one saved workflow template by name

LSP / analysis

Tool	Description
`lsp_diagnostics`	Get live diagnostics (errors, warnings) from attached language servers
`lsp_symbols_overview`	Get a semantic outline of the symbols in a file, including exact selectors for follow-on edits
`lsp_find_symbol`	Find symbols semantically across the workspace and return exact selectors for follow-on edits
`lsp_references`	Find all references to a symbol
`lsp_rename_symbol`	Rename a symbol semantically and apply declaration and reference edits through BMO’s normal write pipeline
`lsp_replace_symbol_body`	Replace the full definition range of a symbol using its exact semantic selector
`lsp_insert_before_symbol`	Insert content immediately before a symbol definition boundary
`lsp_insert_after_symbol`	Insert content immediately after a symbol definition boundary
`lsp_ripple_impact`	Get ranked list of files referencing changed symbols
`lsp_restart`	Restart a language server

Semantic Symbol Workflow

Use the semantic symbol tools when you want symbol-aware navigation or edits instead of grep-first text matching.

Run lsp_symbols_overview when you know the file and need its structure, or lsp_find_symbol when you know the symbol name but not the file.
Copy the exact selector from the result.
Run lsp_rename_symbol, lsp_replace_symbol_body, lsp_insert_before_symbol, or lsp_insert_after_symbol.
If staging is enabled and the edit touches multiple files, review the staged batch before accepting it.

`name_path` vs `symbol_key`

name_path is the human-readable semantic path for a symbol within a file, such as Coordinator.Run. It is the default selector to copy out of discovery results.
symbol_key is the more precise selector when the runtime surfaces it. It is intended for duplicate, overloaded, or otherwise ambiguous symbol paths.
Prefer exact semantic selectors over reconstructing symbol names from raw source text.

Staged Multi-File Behavior

Semantic renames can touch more than one file because the language server may return declaration and reference edits together. BMO routes those edits through the same permission, staging, history, and reflection pipeline as other write tools. When staging is enabled, review the staged batch first and then accept or reject it like any other grouped edit.

Example: Discovery, Rename, Review

Discover the declaration:

{"tool":"lsp_find_symbol","query":"Run","path":"internal/agent"}

Rename using the exact selector returned by discovery:

{
  "tool": "lsp_rename_symbol",
  "file_path": "internal/agent/coordinator.go",
  "name_path": "Coordinator.Run",
  "new_name": "Execute"
}

If BMO stages a multi-file rename, review the staged batch and accept it once the declaration and references look correct.

Agent parity notes

There is no dedicated file_picker or open_editor tool. File attachment and file-editing parity is achieved through send_message, view, edit, write, and apply_patch, which operate directly on workspace paths.
Plugin management has agent parity through plugin_list, plugin_install, plugin_update, and plugin_remove. The mutating plugin tools still require approval because they change the shared plugin directory.
bmo auth <platform> is intentionally human-only bootstrap. It requires browser or device-code handoff, so agents should surface the need to re-authenticate rather than trying to complete the login flow themselves.
Process-lifecycle mutation is gated rather than broadly available. Agents may inspect process-backed state (daemon_status, autopilot_status, schedule_inspect) by default. Starting/stopping/restarting long-lived processes requires operator opt-in with BMO_ENABLE_PROCESS_LIFECYCLE_TOOLS before daemon_restart, autopilot_up, or autopilot_down are registered.
daemon_status is read-only. When a coordinator is present it also reports spawn_isolation_audit, including whether tracked children are session_only, runtime_backed, or mixed, along with bounded PID and cleanup-pending / cleanup-failed counters and per-finding PID-backed orphan evidence when available.

Availability notes

LSP tools appear when BMO can attach a language server for the current workspace.
Staging tools appear when staged file review is enabled for the current run.
sourcegraph is only useful when Sourcegraph access is configured.
semantic_search and find_similar_code require the embedding service to be enabled in config.
MCP resource tools depend on connected MCP servers.
Scheduling and memory tools depend on the relevant runtime features being enabled in config.
decompose_task is only available when orchestrator mode is enabled.

Disabling tools

[options]
disabled_tools = ["web_search", "sourcegraph"]

Restricting one agent to an allowlist

[agents.coder.tools]
allowed = ["view", "grep", "glob", "bash"]

Only the listed tools are offered to that agent. To skip approval prompts without hiding tools, use [permissions].allowed_tools.

Visual: tool taxonomy and gates

Tool taxonomy and gates

Available registryBuilt-in tools, MCP tools, workflow tools, and configured agent tools.

Mode and agent policySession mode, agent kind, disabled tools, and tool categories narrow the set.

Permission boundaryAllowed tools skip prompts; risky actions still require approval unless explicitly configured.

Runnable actionThe agent receives only the effective tool surface for the current run.

If a tool is absent, debug the funnel from registry to permissions before assuming the feature is missing.