# ElevenAgents Tools as Code: Validate the Config Without Editing Production

ElevenLabs' SDK tool builder makes agent tools reviewable in code. Learn where validation happens and why a dev branch does not isolate a shared tool definition.

By Paras Madan | 2026-11-19


ElevenLabs' [November 17 release](https://elevenlabs.io/docs/changelog) adds a tool builder to its Python and JavaScript SDKs from version 2.79.0. You can describe webhook, client and system tools in code instead of maintaining nested configuration by hand. The builder produces requests for the existing create and update APIs; it is not a new execution service.

The useful change is reviewability. A support team's order-lookup tool can have its parameter changes reviewed alongside application code. But putting the definition in Git does not, by itself, make a live tool update safe.

## Start with one read-only tool

Imagine an agent that checks an order's delivery status. The caller supplies an order number, the service returns a status, and the agent explains it. I would start a migration with that narrow workflow rather than a refund or account-change tool.

Write down which values the caller may influence and which must come from your application. A caller-provided order number is not proof that the caller may access that order. Keep that authorization check in the service receiving the request, separate from the model's ability to populate a parameter.

The [builder documentation](https://elevenlabs.io/docs/eleven-agents/customization/agents-as-code/tools) distinguishes model-supplied values, dynamic variables, constants and system-provided values. Each literal needs one value source. Secret headers can reference the workspace secret store instead of embedding credentials in the configuration.

For this example, my review would focus on whether the order identifier is mapped correctly, whether the authentication header stays outside the checked-in file, and whether the returned status is the field the agent actually needs. Those are more useful questions than whether the chained methods look tidy.

## Validate the generated configuration

The builder validates at `build()` and serialization, not at each chained call. Validation errors include a missing path parameter, conflicting value sources and invalid request-body combinations. Serialized JSON uses stable formatting, and existing tools can be loaded without discarding fields the builder does not model.

Make validation a local step before any API write. I would save the resulting JSON, inspect its diff and run the same validation in CI. Reviewers should be able to see whether the change affects a description, parameter or endpoint without opening the dashboard and reconstructing the old state.

Then test the actual service contract. A valid schema can still point to the wrong endpoint or extract the wrong response field. For the order example, use controlled responses for delivered, delayed and unknown orders, plus a service timeout. Check the answer the caller hears, not just whether the request returned successfully.

## A dev branch does not copy a shared tool

ElevenLabs' [safe-editing guide](https://elevenlabs.io/docs/eleven-agents/customization/tools/tool-configuration/editing-tools) explains the important boundary: custom tool definitions are shared workspace records. Agent branches store their IDs, not independent definitions. Updating a tool affects every referencing agent and version immediately; reverting an agent version does not reverse that shared edit.

For an isolated test, the guide recommends copying the tool and attaching the new ID on a development branch. Update workflow references too. Built-in system tools are different: their configuration is versioned with the agent.

In the order example, keep the existing lookup untouched while trying a revised response mapping on the copy. Give the test deployment an unmistakable name and record both IDs in the change request. That makes it harder to accidentally update the production record while working from a development branch.

## Promote the tested reference deliberately

The builder guide says webhook and client tools should be attached by ID. Deprecated inline `prompt.tools` cannot be combined with `tool_ids`, and supplying it replaces built-in tools with the system tools it contains.

Before promotion, inspect the complete agent configuration, not only the new custom tool. An order-lookup improvement should not accidentally remove the agent's ability to end a call or transfer it.

Keep the previous definition available until you have checked the rollout and its dependencies. My acceptance record would contain the configuration diff, test results, old and new IDs, and the person responsible for reversing the change. That turns tools as code into a repeatable deployment practice rather than a faster way to make unreviewed edits.

I'm Paras. I work at the intersection of AI, engineering and distribution.

I help AI teams explain technical products through clear documentation, practical guides and developer-focused content.

[Book a 30-minute call](https://cal.com/paras-madan/30min).
