> ## 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, and turn off web search.
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.
The TypeScript samples assume the `rl` client from [Client setup](/managed-agents/api#client-setup).
## Before you begin
* You need the organization developer or admin role to create, change, or delete agents and their tool settings. The organization user role can view them. See [Organizations and roles](/managed-agents/organizations-and-roles).
* For the API, create a key on [API keys](/managed-agents/api-keys) and export it as `RECURSION_API_KEY`.
* Tool settings belong to an agent version. Read [Update an agent](/managed-agents/agents#update-an-agent) first, because every change is a new version.
## How a session gets its tools
```mermaid theme={"theme":"css-variables"}
flowchart LR
AgentVersion["Agent version"] --> Start["Session start"]
Environment["Environment"] --> Start
Features["Skills, roster, teams"] --> Start
Start --> Snapshot["Tool set fixed for the session"]
```
* **The agent version** decides web search, remote [MCP servers](/managed-agents/mcp-servers), [skills](/managed-agents/skills), the apps it's granted through [integrations](/managed-agents/integrations), and [multi-agent](/managed-agents/multi-agent) roles.
* **The environment** decides the sandbox tools. `computer` needs an environment with computer use turned on. See [Environments](/managed-agents/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.
## Sandbox tools
These tools run inside the session's sandbox and see its `/workspace`.
| 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](/managed-agents/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](/managed-agents/environments-reference), browser tools reach an external site only when the destination is allowed.
## Tools that run outside the sandbox
These tools run outside the sandbox, so they work the same way in every environment.
| 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](/managed-agents/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
| Feature | Tools |
| ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Skills](/managed-agents/skills) | `activate_skill` loads one attached skill's full instructions. Offered when the session has at least one usable skill. |
| [Subagents](/managed-agents/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](/managed-agents/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](/managed-agents/referenced-sessions) | `list_referenced_sessions`, `session_overview`, `session_outline`, `search_events`, `read_events`, `get_event`, `get_team_state`, `get_costs`, `get_outcomes`, `view_event_images`, `list_session_files`, `read_session_file`, and `read_session_skill` read the earlier sessions you granted. |
| [Outcomes](/managed-agents/outcomes) | The grading session that checks a rubric records its verdicts with `submit_evaluation`. The agent being graded does not get this tool. |
Tools from [MCP servers](/managed-agents/mcp-servers) are added next to these. Their names and schemas come from the server and are fixed when the session starts.
Apps granted through [built-in integrations](/managed-agents/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.
## 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`.
1. In the sidebar, click **Agents**, then open the agent.
2. On **Configuration**, find **Tools**.
3. Clear **Web search**.
4. Click **Save new version**.
```typescript theme={"theme":"css-variables"}
const agent = await rl.managedAgents.getAgent({
agent_id: '5f0c2a1e-8b7d-4c3a-9e21-6d4f0b9a7c55',
});
await rl.managedAgents.createAgentVersion({
agent_id: '5f0c2a1e-8b7d-4c3a-9e21-6d4f0b9a7c55',
body: {
base_agent_version_id: agent.latest_agent_version_id,
name: agent.name,
model: agent.model,
system: agent.system,
web_search_enabled: false,
disabled_integration_mcp_providers: ['github'],
},
});
```
```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": "anthropic/claude-sonnet-5",
"system": "Write release notes from the repository.",
"web_search_enabled": false,
"disabled_integration_mcp_providers": ["github"]
}'
```
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": ["github"]
}
```
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](/managed-agents/integrations#native-integrations) providers whose MCP tools an agent's sessions do not receive, even when the agent has access to the connection. It doesn't affect [built-in integrations](/managed-agents/integrations), whose tools are controlled by each app's allow-list. In the console, it's the MCP tools checkbox on each native connection in the agent's **Integrations** section.
The field follows these rules:
* Supported values are `confluence`, `github`, `google`, `jira`, `launchdarkly`, and `loom`. Any other value returns `400 invalid_request`.
* On `createAgent`, omitting the field means `["github"]`.
* On `createAgentVersion`, omitting the field means an empty list.
* The field never affects servers you list in `mcp_servers`.
## Read a session's tool set
A session records the tool settings it started with in `config`. `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 the tables above.
1. In the sidebar, click **Sessions**, then open the session.
2. Each tool call in the transcript shows the tool's name and input.
```typescript theme={"theme":"css-variables"}
const session = await rl.managedAgents.getSession({
session_id: 'b7e1c9a4-3d62-4f15-8a07-5c2e9f6d1b38',
});
console.log(session.config?.available_builtin_tools);
```
```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`.
## What can go wrong
| 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 image cannot start the display. | Turn on computer use in the [environment](/managed-agents/environments) and use an image that includes the display layer. |
| `screenshot` of an external site fails | The environment's network policy blocks the destination. | Allow the destination in the [network policy](/managed-agents/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. |
| 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](/managed-agents/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](/managed-agents/limits) for request and session limits.
## Next steps
Add remote tools and keep their credentials in a vault.
Choose the image, compute, network policy, and computer use.
Ask for deliverables and see how they're kept.
Give the agent procedures it loads when they apply.