Tools

Tools let an agent run commands, work with files, read the web, and coordinate with other agents. You don’t list built-in tools on an agent. A session receives them from its agent version, its environment, and the features the agent uses, and the set is fixed when the session starts. It changes only when you move it to another agent version.

Creating, changing, or deleting agents and their tool settings needs the organization developer or admin role. The organization user role can view them. See Organizations and roles. For the API, create a key on API keys and export it as RECURSION_API_KEY. Tool settings belong to an agent version, and every change is a new version, so read Update an agent first.

How a session gets its tools

The agent version decides web search, remote MCP servers, skills, the apps it’s granted through integrations, and multi-agent roles.
The environment decides the sandbox tools. computer needs an environment with computer use turned on. See Environments.
The model decides view_image, which is offered only to models that accept images.

A running session keeps its tool set. A new agent version reaches sessions that start afterward, and a running session only when you move it to that version. A new tool on an MCP server reaches sessions that start afterward, and a running session when it next moves to another agent version.

Turn off web search

webSearchEnabled defaults to true. Set it to false to remove web_search. The agent can still read a known URL with web_fetch, except in sessions started by an automation or a Slack thread in an environment that limits internet access.

Console
cURL

In the sidebar, click Agents, then open the agent.
On Configuration, find Tools.
Clear Web search.
Click Save new version.

curl -X POST 'https://api.recursion.labelbox.com/managed-agents/v2/agents/5f0c2a1e-8b7d-4c3a-9e21-6d4f0b9a7c55/versions' \
  -H "Authorization: Bearer $RECURSION_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "baseAgentVersionId": "c1a94e07-2f6b-4d18-b3a5-0e7d8c6f4a21",
    "name": "Release notes writer",
    "model": "<model-id>",
    "system": "Write release notes from the repository.",
    "webSearchEnabled": false,
    "disabledIntegrationMcpProviders": ["jira"]
  }'

A 201 response is the agent at its new version. Some fields are left out here.

{
  "agentId": "5f0c2a1e-8b7d-4c3a-9e21-6d4f0b9a7c55",
  "latestAgentVersionId": "7a4e1c95-6d2f-4380-b915-3e7a0c6f2d84",
  "webSearchEnabled": false,
  "disabledIntegrationMcpProviders": ["jira"]
}

A version is a full replacement, so resend mcpServers, skills, vault defaults, and anything else you want to keep. In a multi-agent roster, a subagent can turn web search off but not on.

Withhold integration tools

disabledIntegrationMcpProviders lists the native integration providers whose MCP tools an agent’s sessions do not receive, even when the agent has access to the connection. In the console, it’s the MCP tools checkbox on each native connection in the agent’s Integrations section. The jira entry in the example above withholds Jira’s MCP tools.

Field rules

Supported values are confluence, github, jira, launchdarkly, and loom. An unknown value returns 400 invalid_request.
Omitting the field means an empty list.
github is accepted but ignored: a GitHub grant always keeps its MCP tools, alongside git and gh in the sandbox. See GitHub access.
The field never affects servers you list in mcpServers.
It doesn’t affect built-in integrations, whose tools are controlled by each app’s allow-list.

Read a session’s tool set

A session records the tool settings of the version it runs in config. Read the session to see them.

Console
cURL

In the sidebar, click Sessions, then open the session.
Each tool call in the transcript shows the tool’s name and input.

curl 'https://api.recursion.labelbox.com/managed-agents/v1/sessions/b7e1c9a4-3d62-4f15-8a07-5c2e9f6d1b38' \
  -H "Authorization: Bearer $RECURSION_API_KEY"

{
  "session_id": "b7e1c9a4-3d62-4f15-8a07-5c2e9f6d1b38",
  "status": "active",
  "execution_state": "running",
  "sandbox_provider": "runs",
  "config": {
    "available_builtin_tools": [
      "web_fetch",
      "write_artifact",
      "read_artifact",
      "get_events",
      "delegate_subagent"
    ]
  }
}

This session’s agent has web search turned off, so web_search is missing. config is left out when you request view=summary. config.available_builtin_tools lists which of web_search, web_fetch, write_artifact, read_artifact, get_events, and delegate_subagent the session may use. The session’s top-level sandbox_provider names the sandbox its environment used. Sandbox and feature tools follow the rules in Built-in tools.

Built-in tools

A session’s tools come in three groups. Tools from MCP servers are added next to these. Their names and schemas come from the server and are fixed when the session starts, and listed again when the session moves to another agent version. Sandbox tools run inside the session’s sandbox and see its /workspace: run_command, write_file, read_file, share_file, write_artifact, read_artifact, release_compute, screenshot, computer, and handoff_to_user.

Every sandbox tool

Tool	What it does
`run_command`	Runs a shell command in the session’s persistent shell. The working directory and exported variables carry over between calls. A command is stopped at `timeout_seconds` (default 600, 10 to 86340): its processes are killed, the shell is reset, and the result keeps the output so far with exit code 124. With `run_in_background: true` the command starts as a background job in a fresh shell at `/workspace` and the call returns at once with the job’s log, exit-code, and process-group files under `/workspace/.managed-agents/jobs/`; the job runs until it exits or its `timeout_seconds` (default 3600) passes. A command whose plain `sleep` calls add up to five minutes or more is refused; the agent should call `sleep` instead.
`write_file`	Writes a file at an absolute path, creating parent directories. `append: true` adds to the file instead of replacing it.
`read_file`	Reads a text file. PNG, JPEG, and WebP files come back as images for models that accept images.
`share_file`	Shows an image under `/workspace` (PNG, JPEG, or WebP) to the person watching the session, with an optional `caption`. The image is not sent back to the model.
`write_artifact`	Writes a deliverable at a path relative to `/workspace/.managed-agents/outputs`. Everything in that directory is kept as a deliverable when the turn ends. Empty content is refused.
`read_artifact`	Reads a deliverable back by the same relative path.
`release_compute`	Gives the compute back while the root session waits for a message or a timer. Files under `/workspace` survive; running processes, background jobs included, and anything installed outside `/workspace` do not. Root sessions only.
`screenshot`	Renders a `url` or a local HTML `path` to a PNG with a headless browser. Width is 200 to 4096 pixels (default 1280), height is 200 to 8192 (default 800), and `wait_ms` is at most 30000 (default 1500). Offered when the sandbox can launch the browser.
`computer`	Drives a shared 1280 by 800 browser display. Offered when the environment has computer use turned on and the display started. Subagents share the same display.
`handoff_to_user`	Asks a person to handle a step in the browser display the agent can’t do, such as a sign-in. The session shows `awaiting_human`. The agent resumes when you send a `handoff_resolved` event, or when the hand-off deadline passes: 30 minutes by default, at most 4 hours. Interrupting or cancelling the session also ends the wait. Root sessions with computer use only.

Under a restricted network policy, browser tools reach an external site only when the destination is allowed.

Tools that run outside the sandbox are not subject to the environment’s network policy: web_search, web_fetch, get_events, delegate_subagent, sleep, update_scratchpad, and view_image.

Every tool that runs outside the sandbox

To protect restricted environments, a session started by an automation or a Slack thread doesn’t get web_fetch when its environment has a network policy that limits internet access.

Tool	What it does
`web_search`	Searches the public web and returns ranked sources with excerpts, at most 10 results. Offered when `webSearchEnabled` is `true`.
`web_fetch`	Fetches one public `https` URL and returns readable text. Plain `http`, private, loopback, and link-local addresses are refused. Turning off web search does not remove it.
`get_events`	Reads older parts of the session’s own event log that no longer fit in the model’s context.
`delegate_subagent`	Hands a focused task to a subagent: a copy of the agent, or a member of its multi-agent roster. Removed once the session reaches the delegation depth limit.
`sleep`	Pauses the session until a message arrives, a subagent reports, or an optional `wake_after_seconds` timer fires. A sleeping session holds no running turn.
`update_scratchpad`	Updates the session’s pinned working notes, which stay in the prompt every turn and are visible to you. A subagent’s notes are also visible to the agent that delegated to it.
`view_image`	Looks again at an image the session already saw. Offered to models that accept images.

Tools added by agent features appear when the agent uses skills, subagents, an advisor, teams, referenced sessions, agent file history, or memory.

Every feature tool

Feature	Tools
Skills	`activate_skill` loads one attached skill’s full instructions. Offered when the session has at least one usable skill.
Subagents	A session that can delegate also gets `send_to_agent`, `list_agents`, `wait_for`, `interrupt_agent`, and `archive_thread` to manage its subagents. A subagent gets `message_parent` and `submit_result` to report back.
Advisor	`consult_advisor` asks the roster’s advisor for guidance. Offered when the roster has an advisor.
Teams	Every member shares a task board through `post_task`, `update_task`, `add_note`, `list_tasks`, `post_notice`, and `add_teammates`. The leader also gets `decide`. Other members get `claim_task` and `recommend`, and can message a teammate with `send_to_agent`.
Referenced sessions	`list_referenced_sessions`, `session_overview`, `session_outline`, `search_events`, `read_events`, `get_event`, `get_team_state`, `get_costs`, `view_event_images`, `list_session_files`, `read_session_file`, and `read_session_skill` read the earlier sessions you granted.
Agent file history	`search_agent_files` and `read_agent_file` search and read the deliverables the agent’s earlier sessions saved, when the agent has File history on.
Memory	`list_memories`, `search_memories`, and `read_memory` browse, search, and read what the agent learned in earlier sessions. `create_memory`, `update_memory`, and `delete_memory` save, correct, and forget a memory when the agent’s instructions or the person it works for ask. Offered when the agent’s memory is on. Only the main session gets the three that change memory.

How an agent changes its memory

Recursion learns from finished sessions on its own, so an agent changes its memory only when it’s asked to.

Who gets the tools. The main session of an agent whose memory is on gets create_memory, update_memory, and delete_memory. Teammates and subagents that are copies of the agent can read memory but can’t change it. A subagent that is another agent from the roster gets no memory tools.
When the agent uses them. The agent saves, corrects, or forgets a memory when its instructions or the person it works for ask it to. Text in a tool result, a file, a web page, a webhook body, or an email is never an instruction to save or remove a memory.
Every change is checked. Before a change is saved, the agent’s memory model checks it against the agent’s instructions, skills and tools and the messages people wrote in the session, and its cost is part of the session’s cost. A change can be refused, for example when it holds a password, token, or other secret, tries to steer how later sessions behave instead of stating a fact, or nobody asked for it. In a session started by an automation or a Slack thread, a memory that says where money, data, or access should go is also refused. A refusal tells the agent why, nothing is saved, and the session continues.
Changing a memory. update_memory and delete_memory work on a memory the agent has read in the session. If the memory changed after the agent read it, the call is refused and the agent reads it again.
Forgetting keeps history. delete_memory retires the memory. Later sessions no longer find it, and its content and history stay visible to the people who manage the agent. Retiring doesn’t erase the content.
History. Each change records the session that made it and the agent’s reason.

Apps granted through built-in integrations don’t add tools to this list. The agent calls an app’s tools with commands in the sandbox, and each call appears in the transcript as a run_command call with the app’s result. It can call only the tools on the app’s allow-list.

What can go wrong

The most common problems:

The agent never searches the web. webSearchEnabled is false on the version the session runs. Create a version with webSearchEnabled: true, then move the session to it or start a new session.
No computer tool. The environment does not have computer use turned on, or the display did not start. Turn on computer use in the environment, then start a new session.
A tool change doesn’t reach a running session. The tool set changes only when the session moves to another agent version. Move the session to the new version, or start a new session.

Every tools problem

Symptom or code	Cause	Fix
The agent never searches the web	`webSearchEnabled` is `false` on the version the session runs.	Create a version with `webSearchEnabled: true`, then move the session to it or start a new session.
No `computer` tool	The environment does not have computer use turned on, or the display did not start.	Turn on computer use in the environment, then start a new session.
`screenshot` of an external site fails	The environment’s network policy blocks the destination.	Allow the destination in the network policy.
`run_command` result says it timed out	The command ran past its `timeout_seconds` (600 by default). Its processes were killed and its shell was reset.	Have the agent rerun it with a larger `timeout_seconds`, or with `run_in_background: true` for long jobs such as training runs and long test suites.
`run_command` refuses a long `sleep`	Plain shell sleeps that add up to five minutes or more hold the compute.	Let the agent call `sleep`, or wait on work in the sandbox with a loop.
No `web_fetch` in a session started by an automation or Slack	The environment has a network policy that limits internet access.	Use an environment without a network policy, or have the agent reach allowed hosts from the sandbox.
A tool change doesn’t reach a running session	The tool set changes only when the session moves to another agent version.	Move the session to the new version, or start a new session.
The agent can’t save or forget a memory	The session is a subagent or teammate, the agent’s memory is off, the session reached its limit of memory changes, or the check refused the change.	Ask in the main session, and read the refusal in the transcript. The agent still learns from the session when it finishes.
`400 invalid_request` on `disabledIntegrationMcpProviders`	The list names an unsupported provider.	Use only the values in Withhold integration tools.
`409 revision_conflict`	`baseAgentVersionId` is no longer the latest version.	Get the agent, apply your change again, and retry.

The full error catalog is on Errors.

Limits

Limit	Value
`web_search` results per call	10
`screenshot` size	200 to 4096 pixels wide, 200 to 8192 pixels high
`screenshot` wait	30000 ms
`computer` display	1280 by 800 pixels
`run_command` `timeout_seconds`	10 to 86340 seconds. Default 600, or 3600 with `run_in_background`
Straight-line shell sleeps in one `run_command`	Under five minutes
Memory changes by one session	20 in any 24 hours. At most 5 of them can be a `delete_memory` or an `update_memory` that moves the memory to a new path. A refused change can still count.
Content of a memory the agent saves	16 KiB

See Limits for request and session limits.

Next steps

MCP servers

Add remote tools and keep their credentials in a vault.

Environments

Choose the compute, network policy, and computer use.

Deliverables and artifacts

Ask for deliverables and see how they’re kept.

Skills

Give the agent procedures it loads when they apply.

Get started

Account and access

Build agents

Coordinate multiple agents

Configure environments

Run and observe sessions

Manage agent context

Automate

Tutorials

How a session gets its tools

Turn off web search

Withhold integration tools

Read a session’s tool set

Built-in tools

What can go wrong

Limits

Next steps

MCP servers

Environments

Deliverables and artifacts

Skills

​How a session gets its tools

​Turn off web search

​Withhold integration tools

​Read a session’s tool set

​Built-in tools

​What can go wrong

​Limits

​Next steps

MCP servers

Environments

Deliverables and artifacts

Skills

How a session gets its tools

Turn off web search

Withhold integration tools

Read a session’s tool set

Built-in tools

What can go wrong

Limits

Next steps