Every built-in tool an agent can call. These are the names the Governance policy accepts in Allowed tools / Denied tools, except the tools in Tools you can’t add to a list. The catalog mirrors the runtime’s tool registry, which is the source of truth, and unknown names are rejected on save. (execute_code and web_crawl are not tools; the shell entry point is terminal.)
You don’t pick which tool the agent uses for a given turn — the agent does. You decide which tools to expose.
The coordination board’s tools (share_note, read_board, expand_note) are listed below for completeness but are not configurable in the allow/deny lists — denying them could strand work, so the policy API refuses them.
Some tools can’t be taken away by an agent’s allow or deny list. A project’s coordinator always keeps agent, send_message, list_agents and stop_agent: they are how it gives out its threads. A sub-agent always keeps send_message, and kept only that way it reaches the agent that started it and nobody else. A session whose agents run always keeps send_message, list_agents and stop_agent, so a policy cannot strand work that waits on them. Anywhere else, a policy that denies agent denies starting sub-agents. end_call is always available on a phone call, and an allowlist doesn’t block it. whiteboard_draw, browser_upload_file, office_read and office_edit can’t be named in either list, so an agent that uses an allowlist doesn’t get them.
| Tool | Use for |
|---|
read_file | Read workspace files with line numbers and pagination (offset / limit) — parses documents, describes images |
write_file | Write a file (sensitive paths denied — SSH keys, shell rc, credentials) |
patch | Apply a unified diff or V4A patch |
search_files | Regex across workspace files |
list_files | Directory listing, optionally recursive |
read_file is not text-only. .pdf, Word (.doc / .docx / .docm), Excel (.xls / .xlsx / .xlsm), PowerPoint (.ppt / .pptx / .pptm), OpenDocument (.odt / .ods / .odp) and .rtf are parsed to text by the tool itself, and image files are described by a vision model. Calling read_file on those paths directly is the intended path — no need to shell out to pdftotext or pip-install a parser through terminal. Two limits to plan around: limit defaults to 500 lines and caps at 2000, and a single read over roughly 100K characters is rejected outright (an operator-tunable default) — page through large files with offset / limit.
| Tool | Use for |
|---|
terminal | Shell command in the sandbox (180s default timeout, 50K-char output cap, optional background=true) |
process | Manage background processes started with terminal(background=true) — list / poll / log / wait / kill / write / submit |
| Tool | Use for |
|---|
web_search | Public-web search (Tavily / Exa backends) |
web_extract | Fetch and extract one or more URLs |
Session-scoped browser. Supports user-control handoff for login / MFA / CAPTCHA.
| Tool | Use for |
|---|
browser_navigate | Open a URL |
browser_get_state | Page as a markdown outline with stable @eN refs (format: "json" for the raw node tree with coordinates) |
browser_evaluate | Run JavaScript in the page and return its value — a whole table, a hidden input, every option of a <select> in one call |
browser_click, browser_type, browser_press_key | Interact |
browser_scroll, browser_drag, browser_wait | Navigate / wait |
browser_upload_file | Give files from the chat’s folder to the page’s file input (up to 10). Click the upload button or the file input first. Offered only in a Surogate Desktop chat on a folder of the user’s computer, not in cloud sessions |
browser_screenshot | Save PNG to workspace |
browser_close | Close the session’s browser |
browser_evaluate runs agent-written JavaScript with the page’s full privileges, against whatever the browser is currently signed in to. It is governed like any other tool, but it is the widest reach in the browser toolset — deny it explicitly on agents where you allow the rest of browser_*. See Agent browser.
| Tool | Use for |
|---|
vision_analyze | Analyse a workspace image path, HTTPS URL, or data:image base64 (raster only — PNG/JPEG/WEBP/GIF) |
| Tool | Use for |
|---|
generate_image | Generate an image from a text prompt (optional image-to-image); saved to the workspace and shown inline |
generate_video | Generate a video from a text prompt (optional first-frame image-to-video); blocks until rendered, saved to the workspace |
Availability: each tool is dropped from the agent’s toolset entirely when no model is wired for its role (a per-agent pick under Configure → Model, or a platform preset) — the LLM never sees an unusable tool. Platform-model generation bills the project’s media wallet (a flat few cents per image; a video bills its reported provider cost); BYO image/video models are not metered by Surogate. When the wallet is empty the tool returns an actionable media_budget_exhausted error — nothing is generated or charged — and on monetized agents a buyer without media credits gets media_credits_exhausted with their buy link. See Media generation.
| Tool | Use for |
|---|
memory | add / replace / remove entries in MEMORY.md (agent’s notes) or USER.md (user facts) |
| Tool | Use for |
|---|
skills_list | List skills attached to this agent (the LLM uses this implicitly) |
skill_view | Read a specific skill’s body |
skill_manage | Create / update / delete skills from inside a session |
consult_expert | Delegate to a configured expert (model-backed skill) |
skill_step | Mark where the agent is in a numbered procedure skill: started, completed or skipped for a step id such as s3. It only records the step, which the skill’s path replay shows. Offered only when an attached skill has a procedure graph. If the agent uses a Tool Access allowlist, the allowlist must name skill_step, or the governance gate refuses the call |
| Tool | Use for |
|---|
kb_search_pages | Hybrid search (keywords plus meaning) across the agent’s attached knowledge bases. Returns ranked source and wiki passages with their KB, path and title; the agent reads the best hits with kb_read_page. Falls back to keyword matching if the embedding provider is down |
kb_list_pages | List all pages in a knowledge base, grouped by page type (index / summary / concept) |
kb_read_page | Read the full markdown content of a single wiki page |
Offered only when the agent has a knowledge base attached (and, on a monetized agent, the buyer’s package includes it).
| Tool | Use for |
|---|
fetch_channel_messages | Read recent messages in this Slack channel — limit (default 50, max 200), since (24h, 7d, or 2026-07-01), user (a Slack user id or <@U…> mention). Returns oldest-to-newest |
fetch_channel_file | Fetch a file shared in this Slack channel (by name or Slack file id) into the workspace |
Both are Slack-only: on a session whose effective channel isn’t Slack (Telegram, WhatsApp, website, web) they return an error rather than a result, so allow-listing them on a non-Slack agent buys nothing. Ambient sessions count as Slack. Inbound attachments on the other channels still reach the workspace through the normal attachment path.
| Tool | Use for |
|---|
end_call | End the phone call once the caller says goodbye or the conversation is finished; the agent says one short goodbye first and the call hangs up when it has been spoken. Offered only on voice calls |
| Tool | Use for |
|---|
whiteboard_draw | Draw on the shared whiteboard canvas: text, formulas, simple sketches, filling an empty box the user drew, or placing an artifact. Offered only in whiteboard sessions of an agent with the whiteboard enabled |
| Tool | Use for |
|---|
step_outcome | Close a journey step — outcome (completed, declined, or skipped with the reason in note), optional label (the business’s category for the answers, e.g. green or red). Messages nobody. checkin_outcome is its older name: the runtime still accepts it, and a tool policy that names it is rewritten to step_outcome |
escalate | Raise something to the team now — reason, severity (red when the person got urgent instructions, else yellow), optional to (team members by name, chosen by what they handle). Reaches the team on their channels and the responsible operator’s Inbox; recorded in the Escalations queue |
followup_enroll | Enrol the person writing, or someone they write for, in a journey, after they agreed to be contacted on this channel |
followup_status | The journeys offered and the enrolments of the person writing |
followup_update | Correct the person’s start date, name, who answers for them, phase, timezone or preferred channel; pause or end their follow-up |
followup_contacts | List, add, remove or confirm the people who answer for the person followed; never linked on a name or a newcomer’s word alone |
followup_withdraw_consent | Stop messages to the one writing on this channel, the moment they ask |
send_form | Send a published WhatsApp form instead of asking its questions one by one |
team_overview, team_message_person, team_update_person, team_enroll_person | Team only: a digest of everyone followed, a message to a person word for word, changes to someone’s follow-up, enrolling someone. Each change is previewed and confirmed first |
team_escalation | Team only: take (claim) or resolve an escalation, by person or the latest alert received; the rest of the team is told |
team_tell_member | Team only: pass a team member’s words to one colleague, signed; the answer comes back the same way |
A due step, a reply to it and its deadline each wake the agent with a step context block (journey, step, the person’s day and local date, who is writing, recent outcomes, why it is awake). The agent writes nothing by answering NO_MESSAGE. See Programs and Team and escalations.
| Tool | Use for |
|---|
office_read | Read a Word document (.docx), spreadsheet (.xlsx), presentation (.pptx) or PDF (.pdf) through the agent’s own live editor session, with everyone’s latest edits: view outline (default, paged with start), block (target; for other types range, slide or page) or search (query). Gives each block’s id and hash, comment threads, tracked changes by author in Word, and who else has it open |
office_edit | Edit a .docx, .xlsx, .pptx or .pdf live: ops applied all or none. Word: insert, replace, delete, move, comment, reply, resolve, with Markdown content, placeholder (pending), chart and image blocks. Spreadsheet: set, format, chart, sheet. Deck: slides (whole slides as HTML, built as native shapes), text, notes, order, remove. PDF: pages, fill, add_field, redact, annotate (free_text or stamp). In the other types reply and resolve work on existing comment threads. A target changed since it was read is refused, so the user’s edit wins. A missing document is created blank |
Both exist only where the platform offers the office editor, and only in a chat with a file pane: the web chat, Studio’s Work chat, Surogate Desktop, a project’s threads, and an API session created with "config": {"file_pane": true}. A project’s coordinator and a /mission chat don’t get them.
- The editor is the only writer. While a document is open in the editor, it is changed only through
office_edit. Where the agent has office_edit, a write_file or patch to any .docx, .xlsx, .pptx or .pdf is refused, open or not.
- Pictures are read from the workspace: PNG or JPEG up to 5 MB each (SVG too on slides), at most 12 MB per call.
- Time. An edit has up to 300 seconds; one that times out may still have applied, and the result says so.
- Busy. When the platform has as many documents open for agents as it can hold, the call fails with The office service has as many documents open as it can hold; try again in a minute.
- Saves. Every document a turn edited is saved when the turn ends.
Where the agent has no office_edit, the built-in docx, xlsx, pptx and pdf-forms skills build and change the same files with scripts. See Office documents.
| Tool | Use for |
|---|
github | GitHub REST API over the agent’s configured repos, without a checkout — read (default) or write issues/PRs/files/labels |
run_coding_agent | Run Claude Code or Codex on a configured repo — checks out a branch, implements, commits, pushes, and opens a PR (the /code tool) |
| Tool | Use for |
|---|
agent | Start one sub-agent from a short description and a prompt that stands alone, optionally of a pre-configured agent_type. In a main session it runs in the background: the call returns its agent_id at once and the report arrives as a notification. run_in_background=false waits for the report instead. Several calls in one response run in parallel. |
send_message | Send a running or finished agent a follow-up, a correction or an answer; a finished agent is resumed with its context. A sub-agent reaches its parent with to: "parent". |
list_agents | List the agents the session started, or read one |
stop_agent | Stop an agent, with the agents it started, or a background command |
monitor | Run a command and turn each line it prints into a notification (with terminal: a rule on terminal covers it) |
Coordination board (parallel agents in a group share verified notes):
| Tool | Use for |
|---|
share_note | Post a verified FACT / FAIL / CLAIM / RESULT note to the group’s board |
read_board | Read the group’s consolidated current board state |
expand_note | Expand a board note (by n<ID>) into its underlying source content or artifact |
Ambient channel:
| Tool | Use for |
|---|
mate_ambient_post | Post a proactive, confidence-gated message into the channel during an ambient review (Surogate Mate) |
Project threads: a project’s coordinator gives out its threads with the same tools.
| Call | Use for |
|---|
agent | Start a thread: a separate agent session that does one piece of the project’s work in its own copy and reports back. Returns at once |
send_message | Send a follow-up to a thread; a finished thread runs again with what it already knows |
stop_agent | Stop a working thread; a follow-up starts it again. With resolve: true, mark its work done; it moves to Resolved, and a follow-up reopens it |
list_agents | List the project’s threads with where each stands and its status line; with agent_id, read a thread’s latest report, its files and any question it waits on the user to answer |
Only a project’s coordinator can resolve threads. In a project on the user’s computer, a thread starts once Surogate Desktop there sets up its copy of the project’s folder. A thread’s report reaches the coordinator as a notification, its files in a <files> block.
Hard depth limit: 2 levels of sub-agents beneath the root session.
| Tool | Use for |
|---|
research_memory | Curated evidence bank for deep research — add / retrieve / list cited sources |
research_outline | The living research outline (markdown) — set / get |
| Tool | Use for |
|---|
cron_create | Create a recurring scheduled prompt (5-field cron expression) |
cron_delete, cron_list | Manage schedules |
loop_wait | (Dynamic-loop only) set the next delay in 60–3600s, or signal completion |
loop_complete | (Fixed-cron loop only) mark loop finished from inside a run |
| Tool | Use for |
|---|
ask_user_question | Ask the user up to 5 questions (each up to 4 labeled choices, or up to 10 on Slack, Telegram and WhatsApp, + optional “Other”) in a tabbed chat widget, and wait for the batched answers, for up to 30 minutes. With no answer by then, the turn ends (see When nobody answers). |
How answers arrive depends on the channel:
| Channel | Widget | Typed reply |
|---|
| Web | Yes | Yes — a plain text message while the question is pending is consumed as the answer |
| Telegram | Yes | Yes — same rule |
| Slack | Modal | No — a typed reply gets a nudge toward the modal |
| API service accounts | Respond route only | Never converted |
Typed-reply mapping: text that exactly matches a choice label (case-insensitive) selects that choice; anything else is recorded as an “Other” answer; a multi-question prompt receives the whole reply against each question. Messages with images or attachments are never converted, and the conversion stops working shortly before the 30-minute cap. Once a response exists for the tool call, later messages are ordinary messages.
When no answer comes within 30 minutes, the tool returns cancelled: true with reason: "timeout", and the turn ends there:
- Tool calls queued after the question in the same batch are skipped.
- The model gets one more reply with tools switched off, asked to say only, in one short line, that it will wait (in the person’s language on Slack, Teams, Telegram, WhatsApp and Discord).
- The question’s inbox item expires and takes no more answers. A later reply arrives as an ordinary message, and the tool result tells the model to ask again then if it still needs the answer.
- If a message the model has not read yet arrived during the wait, the turn does not end: it goes on with that message.
- A sub-agent is not offered
ask_user_question: it has no way to the user, and asks the agent that started it with send_message instead.
| Tool | Use for |
|---|
create_artifact | Render a markdown / table / chart / HTML / SVG artifact inline in the chat (500KB max per artifact, 200 per session) |
| Tool | Use for |
|---|
todo | Per-session multi-step task tracker |
session_search | Full-text search the session’s event history |
user_reports | Operator-only: read the agent’s per-user and cohort reports (overview / get / list) |
Any tool an MCP server registers becomes available to attached agents. The MCP proxy injects credentials from the Vault — the agent’s sandbox never sees secrets. See MCP & Vault for setup.
MCP tools (mcp__*) are outside the built-in allow/deny lists: an allowlist doesn’t reject them, and a denylist won’t accept an mcp__* name either. They’re governed by which servers you attach (and, on monetized agents, by the buyer’s package); egress and sandbox checks still apply, and the approval list below is the one place a single MCP tool can be gated by name.
Three lists govern a tool call. Allowlist and denylist are configured per-agent in CONFIG → Tool Access:
- Allowlist — only these built-in tools pass the governance gate. Empty allowlist = all tools (subject to denylist). Note: a tool outside the allowlist is still advertised to the LLM — it’s blocked at call time with a
Blocked: <reason> result, not hidden from the schema.
- Denylist — always blocked. Deny beats allow, and the two lists can’t overlap.
- Approval-required (
require_approval on the agent policy) — the call is held and raised to a human as a governance_gate inbox item; approving lets the agent’s retry of that exact call through. Evaluation order is deny → approval → allow, so a denied tool is never approvable, and this is the only list that accepts mcp__* names. Set it through the agents API: the tool-access form doesn’t render it, and saving that form drops it. See Tools that need approval first.
Lists take exact tool names — there is no prefix or wildcard matching. Common patterns:
| Agent type | Suggested |
|---|
| Customer support | Allow: kb_search_pages, kb_list_pages, kb_read_page, web_search, ask_user_question, create_artifact, memory. Deny: terminal, write_file, patch |
| Code assistant | Allow: read tools + web_search + github. Deny: write_file, patch, terminal |
| Data analyst | Allow everything. Deny: cron_create, cron_delete, cron_list if no scheduling |
| Internal automation bot | Start with denylist only, gate the dangerous ones explicitly |