# MCP tool reference Patterm gives every agent it launches a set of MCP tools for orchestration, processes, timers, todos, scratchpads, worktrees, references, routines, history and diffs. You do not call these yourself. Agents call them, and you can ask an agent to use one by name. Your own MCP servers are separate; see [Your MCP servers](https://patterm.com/docs/mcp-servers.md). ## Conventions - **Names are snake_case.** Every tool name reads the same in every harness, for example `todo_list` or `worktree_attach`. Namespaced tools are called directly by that name. - **Tools are advertised directly.** Agents do not need a discovery step. `help` with a `tool` name returns the schema and usage notes for one tool, and `whoami` with `include_tools: true` lists what the caller can use. - **Project scope.** An agent reads and changes only its own project's records. A `project_id` an agent passes never widens that. Only the [assistant](https://patterm.com/docs/assistant.md) and workspace routines reach across projects. - **Hidden tools.** Settings, MCP server management, host pairing, project creation and similar owner-only tools exist, but they are hidden. Agents can neither list nor call them. - **Host-qualified addresses.** For a project linked across [paired hosts](https://patterm.com/docs/multiple-hosts.md), agents on another host appear in `list_processes` as `host:process`, such as `workstation:process_7`. Read tools accept these addresses. Agents never control another host's agents; they send them messages with `send_message`. Some tools are only offered in certain cases. `ui_save` is offered to [Integrated](https://patterm.com/docs/agents-and-processes.md#integrated-and-tui-agents) agents when Figures are on. `host_read` and the `host` option of routine tools need a linked project. `assistant_*` tools are for the assistant only. ## Orchestration | Tool | Purpose and key parameters | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `spawn_agent` | Start a child agent. Needs one of `agent` (`claude`, `codex`, `opencode`, `rawpty`), `preset`, or `conversation_id` (resume an earlier conversation). Also `prompt`, `agent_instructions`, `name`, `model`, `reasoning`, `service_tier` (Codex), `worktree_id`, and `detached` (open as a top-level tab with no parent). | | `spawn_process` | Start a terminal or command as a child. `kind` is `command` (default) or `terminal`; also `argv`, `shell`, `name`, `working_dir`, `worktree_id`, `detached`. | | `send_message` | `target_process_id` and `message`. The target can be a process ID, `host:process`, `parent` (from a child), or `assistant`. | | `report_to_parent` | `body`, `status` (`completed`, `blocked`, `failed`, `no_findings`) and an optional `title`. Fails for agents with no parent. | | `notify_user` | `title`, optional `message` and `urgency` (`low`, `normal`, `high`). Only when blocked on a human decision. Children are routed to their parent. | | `request_close` | `summary`. Asks to be closed when the task is complete. You choose Close or Keep open; a child's request goes to its parent. | | `notification_list` | Lists notifications for the project, open ones by default. Optional `process_id`, `include_resolved`, `limit`, `offset`. Read-only. | See [Agents that run agents](https://patterm.com/docs/orchestration.md) and [Notifications and close requests](https://patterm.com/docs/notifications.md). ## Processes | Tool | Purpose and key parameters | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `list_processes` | List processes. `status` is `running` (default) or `all`; also `kind`, `limit`. Includes `host:process` entries from linked hosts. | | `get_project_status` | Project, caller and process orientation. | | `get_process_status` | Status of one `process_id`. | | `get_process_output` | One read of a terminal's rendered viewport, or the recent conversation of an Integrated agent. Optional `max_lines`, `max_bytes`. Not for waiting. | | `get_conversation_output` | Read an agent's conversation in pages, newest first, with `latest_answer`, turn state and last report. `limit`, `before` (the previous page's `next_before`), `include` (`tools`, `reasoning`, `notices`), `max_bytes`. | | `search_output` | Find a `pattern` in a process's output. | | `wait_for_pattern` | Wait up to `timeout_seconds` (default 30) for a `pattern` to appear in terminal output. | | `send_input` | Type into a process. `kind` is `text`, `paste` or `key`; also `text`, `key`, `submit`, `wait_ms`, `tail_mode`. | | `restart_process` | Restart a persistent process. | | `stop_process` | Stop a process. | | `close_process` | Close a process entry and its children. | | `rename_process` | Rename a process (`process_id`, `name`). | | `session_rename` | Rename your own session to describe the current work. A title you set yourself wins. | | `get_process_ports` | Ports seen in a terminal's output. | ## Timers | Tool | Purpose and key parameters | | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `timer_set` | Fire after `seconds`, sending `body`. Also `label`, `owner_process_id`. | | `timer_fire_when_reported_all` | Fire when every process in `watched` has reported or stopped. Takes `body`, optional `max_wait_seconds`, `label`, `owner_process_id`. | | `timer_fire_when_reported_any` | Same, for the first. | | `timer_fire_when_idle_all` | Fire when every watched process is quiet. Same parameters. | | `timer_fire_when_idle_any` | Fire when any watched process is quiet. Same parameters. | | `timer_list`, `timer_pause`, `timer_resume`, `timer_cancel` | Manage timers. The last three take `timer_id`. | `max_wait_seconds` is a rescue timeout. See [Timers and routines](https://patterm.com/docs/timers-and-routines.md). ## Routines Routines are durable schedules. They take an optional `host` to act on a paired host, except `routine_run_now`. | Tool | Purpose and key parameters | | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `routine_list` / `routine_get` | Read routines (`routine_id` for get). | | `routine_create` | Weekly routine. `name`, `days` (0 Sunday to 6 Saturday), `time` (HH:MM), `timezone`, `prompt`, `harness`, `preset` or `model`, `reasoning`, `service_tier`, `delivery` (`notification` or `none`), `worktree_id`, `project_id`. | | `routine_schedule_once` | Run once. `name`, `prompt`, and `in_minutes` or `run_at`. | | `routine_update` / `routine_delete` | Change or remove by `routine_id`. `enabled: false` pauses. | | `routine_run_now` | Start a run now. Always local. | | `routine_runs` / `routine_log` / `routine_run` | Read runs for a routine, recent reports, and one run with its full report (`run_id`). | ## Todos | Tool | Purpose and key parameters | | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `todo_create` | `title`, `notes`, `status` (`backlog`, `open`, `in_progress`, `completed`), `priority` (`low`, `medium`, `high`), optional `assignee_id`. | | `todo_list` | Filter by `status`, `priority`, `assignee_id`, `blocked`, `query`. Paged with `limit` and `offset`. | | `todo_get` | One todo by `todo_id`. | | `todo_update` | Edit with the current `revision`. Set `status` to `completed` to complete, `open` to reopen. | | `todo_delete` | Delete with `revision`. | | `todo_assign` / `todo_unassign` | Omit `assignee_id` to use yourself. | | `todo_dependency_add` / `todo_dependency_remove` | `todo_id` and `blocker_id`. Dependencies mark blockers; they do not control processes. | | `todo_lease_acquire` / `todo_lease_renew` / `todo_lease_release` | Exclusive, expiring ownership of a todo. `ttl_seconds` is 1 to 86400 (default 300). Keep the returned token to renew or release. | Edits and deletions need the record's current `revision`. If another change got there first, fetch the latest and try again. See [Todos and scratchpads](https://patterm.com/docs/todos-and-scratchpads.md). ## Scratchpads | Tool | Purpose and key parameters | | ----------------------------------------- | ----------------------------------------------------------------------------------------------- | | `scratchpad_create` | `title`, `body`, optional `session_id` to attach in the same call. | | `scratchpad_list` | `status` (`active`, `archived`), `query`, `limit`, `offset`. | | `scratchpad_get` | `scratchpad_id`; `mode` (`full`, `content`, `headings`), `offset`, `limit` (lines, up to 1000). | | `scratchpad_update` | Replace content or metadata with `revision`. `status` archives or restores. | | `scratchpad_append` | Append `body` atomically. `revision` is optional. | | `scratchpad_delete` | Delete with `revision`. | | `scratchpad_attach` / `scratchpad_detach` | Link to a session. Agents may omit `session_id`. | ## Worktrees and diffs | Tool | Purpose and key parameters | | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `worktree_create` | Create a project worktree with a branch derived from `name`. `base_ref` defaults to `HEAD`. Also links it to the calling agent. | | `worktree_link` | Register an existing worktree directory (`worktree_path`). Also links it to the calling agent. | | `worktree_list` | List the project's worktrees. | | `worktree_attach` / `worktree_detach` | Link or unlink a `worktree_id` to a session without touching files. A session links at most 10. | | `worktree_abandon` | Remove a worktree's registration. Its directory and branch are kept. | | `diff_current` | Summary of changes in a worktree, without patch text. `scope` is `branch` (default) or `uncommitted`. | | `diff_file` | Old and new contents of one `path` from the diff. | For worktrees see [Worktrees](https://patterm.com/docs/worktrees.md), and for diffs [Diff review](https://patterm.com/docs/diff-review.md). Agents can omit `worktree_id` in `diff_current` and `diff_file` to use their own session's worktree. ## References and session context | Tool | Purpose and key parameters | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `reference_attach` | Attach a verified http(s) `url` to a todo, scratchpad or session (`target_type`, `target_id`). `provider` is `generic`, `linear` or `github`; `resource_type` is `generic`, `issue` or `pull_request`; also `identifier`, `external_id`, `title`. | | `reference_list` | List references on a target. | | `reference_update` | Edit with `revision`. | | `reference_detach` | Remove by `reference_id`. | | `session_context` | An agent's worktrees, assigned todos, attached scratchpads and references. | Patterm stores the links and does not fetch or change the issue or pull request. See [Links to issues and PRs](https://patterm.com/docs/links.md). ## History and search | Tool | Purpose and key parameters | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `search_conversation_history` | Search earlier conversations in the project (`query`, optional `provider`, `limit`). Pass a result's `conversation_id` to `spawn_agent` to continue it. | | `history_list` | List imported conversations. Filter by `provider` (`claude`, `codex`, `opencode`), `session_id`, `resumable`; paged. | | `history_get` | Read one conversation with a message window (`conversation_id`, `anchor_message_id`, `limit`, `offset`). | | `search` | Search sessions, timeline and history records (`query`, `kinds`, `limit`). Raw terminal logs are not indexed. | ## Harnesses | Tool | Purpose and key parameters | | ----------------- | -------------------------------------------------------------------------- | | `harness_list` | Installed harnesses with status and version. | | `harness_presets` | Your configured model presets. Use a preset name with `spawn_agent`. | | `harness_models` | The cached model catalogue, with reasoning levels and Codex service tiers. | ## Figures | Tool | Purpose and key parameters | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ui_save` | Save a chart, table or diagram as a figure for the agent's reply. It returns a reference to put on its own line in the reply. Only Integrated agents get it, and only while Figures are on in settings. | ## Hosts and the assistant | Tool | Purpose and key parameters | | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | `host_read` | Run a read-only tool on a paired host: `host`, `tool` (such as `todo_list`, `worktree_list`, `diff_current`) and `arguments`. | | `assistant_overview` | Assistant only. Every project with its running agents, plus open notifications. | | `assistant_focus`, `assistant_focus_set` | Assistant only. Read Focus mode state, or turn it on or off with `enabled`. | | `assistant_memory_read`, `assistant_memory_search`, `assistant_memory_write` | Assistant only. Saved memory, offered when memory is on. | ## Meta | Tool | Purpose and key parameters | | -------- | ------------------------------------------------------------------------------------------ | | `whoami` | The caller's identity, role, parent and project. `include_tools: true` adds the tool list. | | `help` | Schema and usage notes for one `tool`. | ## Related - [Agents that run agents](https://patterm.com/docs/orchestration.md) - [Timers and routines](https://patterm.com/docs/timers-and-routines.md) - [Your MCP servers](https://patterm.com/docs/mcp-servers.md) --- This is one page of the Patterm documentation. The index of every page is at https://patterm.com/llms.txt.