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.

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, or a new tool on an MCP server, reaches only sessions that start afterward.

Turn off web search

web_search_enabled 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/v1/agents/5f0c2a1e-8b7d-4c3a-9e21-6d4f0b9a7c55/versions' \
  -H "Authorization: Bearer $RECURSION_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "base_agent_version_id": "c1a94e07-2f6b-4d18-b3a5-0e7d8c6f4a21",
    "name": "Release notes writer",
    "model": "<model-id>",
    "system": "Write release notes from the repository.",
    "web_search_enabled": false,
    "disabled_integration_mcp_providers": ["jira"]
  }'

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

{
  "agent_id": "5f0c2a1e-8b7d-4c3a-9e21-6d4f0b9a7c55",
  "latest_agent_version_id": "7a4e1c95-6d2f-4380-b915-3e7a0c6f2d84",
  "web_search_enabled": false,
  "disabled_integration_mcp_providers": ["jira"]
}

A version is a full replacement, so resend mcp_servers, 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

disabled_integration_mcp_providers 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 works only through GitHub’s MCP tools.
The field never affects servers you list in mcp_servers.
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 it started with 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. 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 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 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 `web_search_enabled` 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, or agent file history.

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.

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. web_search_enabled is false on the version the session used. Create a version with web_search_enabled: true, then 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 is fixed when the session starts. Start a new session.

Every tools problem

Symptom or code	Cause	Fix
The agent never searches the web	`web_search_enabled` is `false` on the version the session used.	Create a version with `web_search_enabled: true`, then 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` 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 is fixed when the session starts.	Start a new session.
`400 invalid_request` on `disabled_integration_mcp_providers`	The list names an unsupported provider.	Use only the values in Withhold integration tools.
`409 revision_conflict`	`base_agent_version_id` 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
Straight-line shell sleeps in one `run_command`	Under five minutes

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