> ## 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.

<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](/recursion/organizations-and-roles). For the API, create a key on [API keys](/recursion/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](/recursion/agents#update-an-agent) first.
</Note>

## How a session gets its tools

* **The agent version** decides web search, remote [MCP servers](/recursion/mcp-servers), [skills](/recursion/skills), the apps it's granted through [integrations](/recursion/integrations), and [multi-agent](/recursion/multi-agent) roles.
* **The environment** decides the sandbox tools. `computer` needs an environment with computer use turned on. See [Environments](/recursion/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.

<Tabs>
  <Tab title="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>

  <Tab title="cURL">
    ```bash theme={"theme":"css-variables"}
    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"]
      }'
    ```
  </Tab>
</Tabs>

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

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

<Accordion title="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](/recursion/integrations), whose tools are controlled by each app's allow-list.
</Accordion>

## Read a session's tool set

A session records the tool settings it started with in `config`. Read the session to see them.

<Tabs>
  <Tab title="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>

  <Tab title="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"
    ```
  </Tab>
</Tabs>

```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](/recursion/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`.

<Accordion title="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](/recursion/artifacts) 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](/recursion/environments-reference), browser tools reach an external site only when the destination is allowed.
</Accordion>

**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 title="Every tool that runs outside the sandbox">
  To protect restricted environments, a session started by an [automation](/recursion/automations) 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](/recursion/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. |
</Accordion>

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

<Accordion title="Every feature tool">
  | Feature | Tools |
  | - | - |
  | [Skills](/recursion/skills) | `activate_skill` loads one attached skill's full instructions. Offered when the session has at least one usable skill. |
  | [Subagents](/recursion/multi-agent) | 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](/recursion/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](/recursion/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](/recursion/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. |
</Accordion>

Apps granted through [built-in integrations](/recursion/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](/recursion/environments), 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.

<Accordion title="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](/recursion/environments), 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](/recursion/environments-reference). |
  | `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](#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](/recursion/errors).
</Accordion>

## 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](/recursion/limits) for request and session limits.

## Next steps

<CardGroup cols={2}>
  <Card title="MCP servers" href="/recursion/mcp-servers">
    Add remote tools and keep their credentials in a vault.
  </Card>

  <Card title="Environments" href="/recursion/environments">
    Choose the compute, network policy, and computer use.
  </Card>

  <Card title="Deliverables and artifacts" href="/recursion/artifacts">
    Ask for deliverables and see how they're kept.
  </Card>

  <Card title="Skills" href="/recursion/skills">
    Give the agent procedures it loads when they apply.
  </Card>
</CardGroup>