> ## Documentation Index
> Fetch the complete documentation index at: https://docs.labelbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools

> See which tools an agent gets in a session, turn off web search, and withhold integration 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](https://docs.labelbox.com/recursion/sessions.md#move-a-session-to-another-version).

> [!NOTE]
>
> 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](https://docs.labelbox.com/recursion/organizations-and-roles.md). For the API, create a key on [API keys](https://docs.labelbox.com/recursion/api-keys.md) 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](https://docs.labelbox.com/recursion/agents.md#update-an-agent) first.

## How a session gets its tools

* **The agent version** decides web search, remote [MCP servers](https://docs.labelbox.com/recursion/mcp-servers.md), [skills](https://docs.labelbox.com/recursion/skills.md), the apps it's granted through [integrations](https://docs.labelbox.com/recursion/integrations.md), and [multi-agent](https://docs.labelbox.com/recursion/multi-agent.md) roles.
* **The environment** decides the sandbox tools. `computer` needs an environment with computer use turned on. See [Environments](https://docs.labelbox.com/recursion/environments.md).
* **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](https://docs.labelbox.com/recursion/sessions.md#move-a-session-to-another-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.

> [tab] Console
>
> 1. In the sidebar, click **Agents**, then open the agent.
> 2. On **Configuration**, find **Tools**.
> 3. Clear **Web search**.
> 4. Click **Save new version**.

> [tab] cURL
>
> ```bash theme={"theme":"css-variables"}
> 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.

```json theme={"theme":"css-variables"}
{
  "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 [integration](https://docs.labelbox.com/recursion/integrations.md#more-integrations) 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 connection in the agent's **Integrations** section. The `jira` entry in the example above withholds Jira's MCP tools.

> [accordion] 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](https://docs.labelbox.com/recursion/github.md).
> * The field never affects servers you list in `mcpServers`.
> * It doesn't affect [built-in integrations](https://docs.labelbox.com/recursion/integrations.md), 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.

> [tab] Console
>
> 1. In the sidebar, click **Sessions**, then open the session.
> 2. Each tool call in the transcript shows the tool's name and input.

> [tab] cURL
>
> ```bash theme={"theme":"css-variables"}
> curl 'https://api.recursion.labelbox.com/managed-agents/v1/sessions/b7e1c9a4-3d62-4f15-8a07-5c2e9f6d1b38' \
>   -H "Authorization: Bearer $RECURSION_API_KEY"
> ```

```json theme={"theme":"css-variables"}
{
  "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).

## Built-in tools

A session's tools come in three groups. Tools from [MCP servers](https://docs.labelbox.com/recursion/mcp-servers.md) 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`.

> [accordion] 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](https://docs.labelbox.com/recursion/artifacts.md) 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](https://docs.labelbox.com/recursion/environments-reference.md), 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`.

> [accordion] Every tool that runs outside the sandbox
>
> To protect restricted environments, a session started by an [automation](https://docs.labelbox.com/recursion/automations.md) 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](https://docs.labelbox.com/recursion/multi-agent.md) 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.

> [accordion] Every feature tool
>
> | Feature | Tools |
> | - | - |
> | [Skills](https://docs.labelbox.com/recursion/skills.md) | `activate_skill` loads one attached skill's full instructions. Offered when the session has at least one usable skill. |
> | [Subagents](https://docs.labelbox.com/recursion/multi-agent.md) | 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](https://docs.labelbox.com/recursion/teams.md) | 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](https://docs.labelbox.com/recursion/referenced-sessions.md) | `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](https://docs.labelbox.com/recursion/agent-file-history.md) | `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. |

> [accordion] 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](https://docs.labelbox.com/recursion/automations.md) 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.

In new sessions, the agent calls the tools of apps granted through [built-in integrations](https://docs.labelbox.com/recursion/integrations.md) outside the sandbox, and each call appears in the transcript as a tool 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](https://docs.labelbox.com/recursion/environments.md), 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](https://docs.labelbox.com/recursion/sessions.md#move-a-session-to-another-version) to the new version, or start a new session.

> [accordion] 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](https://docs.labelbox.com/recursion/environments.md), 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](https://docs.labelbox.com/recursion/environments-reference.md). |
> | `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](https://docs.labelbox.com/recursion/sessions.md#move-a-session-to-another-version) 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](#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](https://docs.labelbox.com/recursion/errors.md).

## 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](https://docs.labelbox.com/recursion/limits.md) for request and session limits.

## Next steps

> [card] [MCP servers](https://docs.labelbox.com/recursion/mcp-servers.md)
>
> Add remote tools and keep their credentials in a vault.

> [card] [Environments](https://docs.labelbox.com/recursion/environments.md)
>
> Choose the compute, network policy, and computer use.

> [card] [Deliverables and artifacts](https://docs.labelbox.com/recursion/artifacts.md)
>
> Ask for deliverables and see how they're kept.

> [card] [Skills](https://docs.labelbox.com/recursion/skills.md)
>
> Give the agent procedures it loads when they apply.
