Editing tools safely | ElevenLabs Documentation

This guide shows you how to change a tool used by a production agent without affecting live conversations. It explains what agent versioning tracks for tools, what environment variables can change, how to find everything that uses a tool, and a workflow for testing a tool change on a branch.

How tools relate to branches and versions

Custom tools and system tools are stored in different places, so versioning treats them differently.

Custom tools are shared workspace records

Webhook, client and code tools are workspace records. You create them with Create tool or in the dashboard, then attach them to an agent by ID in conversation_config.agent.prompt.tool_ids. Workflow tool nodes also reference tools by ID.

A branch version stores only these tool IDs, not the tool’s definition. The definition lives on the tool record, and Update tool takes no branch or version parameter. Editing a custom tool therefore has these effects:

The change applies right away to every agent, branch and version that uses the tool, including the main branch.
Going back to an earlier version doesn’t undo the edit, because that version references the same tool ID.
A branch can add or remove tools, but it can’t hold its own copy of a tool’s definition.

Editing a custom tool from a non-main branch doesn’t keep main untouched. To test a change in isolation, follow the testing workflow below.

What a branch versions

Item	Stored on	Versioned per branch
Which custom tools are attached (`tool_ids`)	Agent configuration	Yes
Tool references in workflow nodes	Agent workflow	Yes
System tool configuration (`built_in_tools`)	Agent configuration	Yes
Custom tool definition: name, description, parameters, URL, `execution_mode`	Tool record	No
Tool mock responses (`response_mocks`)	Tool record	No
Tool references in tests	Test record (`referenced_tool`)	No

The tools configuration listed under versioned settings refers to which tools are attached and to system tool settings. It doesn’t cover the definitions of custom tools.

System tools are part of the agent configuration

System tools such as transfer_to_number and end_call are configured inside each agent’s own configuration, under conversation_config.agent.prompt.built_in_tools. They aren’t shared records, so they’re versioned with the branch like the rest of the agent configuration.

Two agents, or two branches of the same agent, can have different system tool settings, such as different transfer numbers and conditions. To change a system tool safely, edit it on a non-main branch and merge the branch when you’ve tested it.

What environment variables can change

Environment variables resolve different values for the same tool depending on the conversation’s environment. For a webhook tool, they can change:

The URL, with {{system__env_<label>}} templates.
Request header values, with secret variables.
The auth connection, with auth connection variables.

Environment variables only swap values. They can’t change a tool’s name, description, parameters or execution mode. Those fields are the same in every environment.

If your change only points a tool at a different endpoint or credential, use environment variables instead of duplicating the tool. If it changes the tool’s description, parameters or behavior, use the workflow below.

The environment is chosen when a conversation starts and applies to the whole conversation. To route test traffic, pass environment when starting the conversation, select an environment in a Simulation test, or pin a phone number to an environment and a branch.

Check what uses a tool before editing it

Before you edit a tool, find the agents and branches that depend on it.

Dashboard

CLI

SDK

Open the tool from your tools list. The tool’s page lists the agents that depend on it.

The Get dependent agents response contains:

agents: agents whose main configuration uses the tool, either in tool_ids or in a workflow node.
branches: non-archived branches whose latest version lists the tool in tool_ids, with agent_id, agent_name, branch_id, branch_name and is_main.
has_more and next_cursor: pass next_cursor as cursor to fetch the next page. page_size defaults to 30 and can’t exceed 100.

Treat the result as a minimum, not a complete list. It can miss a tool that is used only in a workflow node on a non-main branch, or only in a procedure. It also doesn’t report earlier versions, archived branches, or tests that reference the tool.

Test a tool change without affecting production

Because a branch can swap which tool it uses but can’t hold its own tool definition, test a change on a copy of the tool. This example changes a tool that the main branch uses.

Check dependencies and capture current behavior

Check what uses the tool so you know which agents and branches rely on the current definition. Create tests that capture the expected behavior before you branch.

Duplicate the tool

Create a copy of the tool, then make your changes to the copy, not the original.

Dashboard

CLI

SDK

In your tools list, open the actions menu for the tool and select Duplicate tool. This is available for webhook and client tools. It creates a copy named copy_<original-name> that includes the original’s mock responses.

The copy has a different name, and the name is what the LLM sees when it decides to call the tool. If your system prompt refers to the tool by name, update the prompt on the dev branch in the next step as well.

Attach the copy on a dev branch

Create a branch from the main branch’s current version. On that branch, replace the original tool’s ID with the copy’s ID in tool_ids.

Dashboard

CLI

SDK

Open the agent, select the menu next to Publish, and select View all branches.
Click Create branch, create the branch from main, and switch the agent to the new branch.
In the Tools section, remove the original tool, then click Add tool and select the copy.
Click Publish to save a new version on the dev branch.

If you’ve already made the swap on main without publishing, select Publish to a new branch from the menu next to Publish instead. Your unpublished changes go to the new branch and main stays unchanged.

If a workflow node on the branch references the original tool, update that node to use the copy as well.

Test the branch with mocked tools

Run Simulation tests against the dev branch. Use tool mocking so the copy returns controlled responses instead of calling live systems, and set the fallback behavior to Finish with error if a test must never reach the real tool. System tools and workflow tools are never mocked.

Dashboard

CLI

SDK

Switch the agent to the dev branch and open its Tests tab. Tests you run there run against the selected branch.

To test with live calls, pin a test phone number to the dev branch and a non-production environment. To try the change on a share of real traffic, deploy a small percentage to the branch.

Merge the branch

Preview the merge and confirm that tool_ids on the main branch will contain the copy’s ID. Then merge the branch.

Dashboard

CLI

SDK

On the agent’s branches page, open the actions menu for the dev branch and select Merge branch. Choose main as the target and review the result before you confirm.

The main branch now uses the copy, and the original tool is unchanged. Earlier versions of the main branch still reference the original tool, so going back to one of them restores the old tool definition as well.

Update the remaining references by hand

Merging only changes this agent’s configuration. Update these references manually:

Workflow nodes on other branches, and other agents, that should move to the copy.
Tool Call tests whose referenced_tool points at the original tool’s ID.

Keep the original tool while anything still depends on it. Once nothing does, you can delete it.

Next steps

Versioning

Create branches, deploy traffic and merge changes

Environment variables

Resolve tool URLs, headers and auth connections per environment

Testing

Run Simulation tests with mocked tools

Get dependent agents

List the agents and branches that use a tool