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.
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 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, 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 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 and Notifications and close requests.
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.
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.
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, and for diffs Diff review. 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.
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. |
| 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. |
| 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. |