For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Connect
BlogHelp CenterAPI PricingSign up
OverviewElevenCreativeElevenAgentsElevenAPIAPI referenceChangelog
OverviewElevenCreativeElevenAgentsElevenAPIAPI referenceChangelog
  • Get started
    • Overview
    • Quickstart
  • Configure
    • Overview
    • Voice & language
    • Knowledge base
    • Tools
    • Personalization
    • Authentication
  • Deploy
    • Overview
    • Environment variables
    • WhatsApp
    • Batch calls
  • Monitor
    • Overview
    • Users
    • Testing
    • Experiments
    • Versioning
    • Conversation Analysis
    • Analytics
    • Real-time monitoring
    • Privacy
    • Cost optimization
    • CLI
  • Advanced
    • Events
    • Custom models
    • LLM cascading
    • Post-call webhooks
  • Resources
    • UI components
  • Guides
    • Chat Mode
    • Burst pricing
    • ElevenLabs' docs agent
    • Scaling user interviews
    • Simulate Conversations
      • Agent tools deprecation
LogoLogo
Login
Login
Connect
BlogHelp CenterAPI PricingSign up
On this page
  • Overview
  • What’s changing?
  • Critical deadlines
  • Why the change?
  • What has already happened?
  • Deprecation timeline
  • Toolbox endpoint
  • Migration guide
  • Example payloads
  • FAQ
Deprecations

Agent tools deprecation

Migrate from legacy prompt.tools to the new prompt.tool_ids field.

Was this page helpful?
Previous
Built with

Overview

The way you wire tools into your ConvAI agents is getting a refresh.

What’s changing?

  • The old request field body.conversation_config.agent.prompt.tools is deprecated.
  • Use body.conversation_config.agent.prompt.tool_ids to list the IDs of the client or server tools your agent should use.
  • New field prompt.built_in_tools is introduced for system tools (e.g., end_call, language_detection). These tools are referenced by name, not by ID.

Critical deadlines

July 14, 2025 - Last day for full backwards compatibility. You can continue using prompt.tools until this date.

July 15, 2025 - GET endpoints will stop returning the tools field. Only prompt.tool_ids will be included in responses.

July 23, 2025 - Legacy prompt.tools field will be permanently removed. All requests containing this field will be rejected.

Why the change?

Decoupling tools from agents brings several advantages:

  • Re-use – the same tool can be shared across multiple agents.
  • Simpler audits – inspect, update or delete a tool in one place.
  • Cleaner payloads – agent configurations stay lightweight.

What has already happened?

Good news — we’ve already migrated your data! Every tool that previously lived in prompt.tools now exists as a standalone record, and its ID is present in the agent’s prompt.tool_ids array. No scripts required.

We have automatically migrated all existing data:

  • Every tool that was previously in an agent’s prompt.tools array now exists as a standalone record.
  • The agent’s prompt.tool_ids array already references those new tool records.

No one-off scripts are required — your agents continue to work unchanged.

Deprecation timeline

DateStatusBehaviour
July 14, 2025✅ Full compatibilityYou may keep sending prompt.tools. GET responses include the tools field.
July 15, 2025⚠️ Partial compatibilityGET endpoints stop returning the tools field. Only prompt.tool_ids included.
July 23, 2025❌ No compatibilityPOST and PATCH endpoints reject any request containing prompt.tools.

Toolbox endpoint

All tool management lives under a dedicated endpoint:

Tool management
1POST | GET | PATCH | DELETE  https://api.elevenlabs.io/v1/convai/tools

Use it to:

  • Create a tool and obtain its ID.
  • Update it when requirements change.
  • Delete it when it is no longer needed.

Anything that once sat in the old tools array now belongs here.

Migration guide

System tools are not supported in prompt.tool_ids. Instead, specify them in the new prompt.built_in_tools field.

If you are still using the legacy field, follow the steps below.

1

1. Stop sending prompt.tools

Remove the tools array from your agent configuration.

2

2. Send the tool IDs instead

Replace it with prompt.tool_ids, containing the IDs of the client or server tools the agent should use.

3

3. (Optional) Clean up

After 23 July, delete any unused standalone tools via the toolbox endpoint.

Example payloads

A request must include either prompt.tool_ids or the legacy prompt.tools array — never both. Sending both fields results in an error.

1{
2  "conversation_config": {
3    "agent": {
4      "prompt": {
5        "tools": [
6          {
7            "type": "client", 
8            "name": "open_url",
9            "description": "Open a provided URL in the user's browser."
10          },
11          {
12            "type": "system",
13            "name": "end_call", 
14            "description": "",
15            "response_timeout_secs": 20,
16            "params": {
17              "system_tool_type": "end_call"
18            }
19          }
20        ]
21      }
22    }
23  }
24}

FAQ

Will my existing integrations break?

No. Until July 23, the API will silently migrate any prompt.tools array you send. However, starting July 15, GET and PATCH responses will no longer include full tool objects. After July 23, any POST/PATCH requests containing prompt.tools will be rejected.

Can I mix both fields in one request?

No. A request must use either prompt.tool_ids or prompt.tools — never both.

How do I find a tool's ID?

List your tools via GET /v1/convai/tools or inspect the response when you create one.