Editing a tool fails a lot, almost always because the patch violated a per-type schema rule or dropped a field the caller never read. The fix: read the current tool first, send a minimal but complete-per-object patch. All calls use xi-api-key: $API_KEY against https://api.elevenlabs.io.

1. Read the current tool first

Do not edit blind; the failures come from patching a shape you never read.

GET /v1/convai/tools to get the exact tool id and its TYPE (webhook / client / code). The type determines the config shape.
GET /v1/convai/tools/{tool_id} to read the tool's CURRENT saved config: name, description, request_body_schema properties, request_headers, auth, response assignments, response_timeout_secs, and (for client tools) expects_response / execution_mode.
GET /v1/convai/agents/$AGENT_ID?branch_id=$BRANCH_ID to confirm the tool is attached (tool_ids / per-node additional_tool_ids) and to see which nodes reference it before you rename anything.

2. Update with the full config

PATCH /v1/convai/tools/{tool_id}

PATCH REPLACES the config, so send the config for the type you read in step 1 with your changes applied. Change only what the user asked, but include the FULL object for any nested field you touch: if you edit one property in request_body_schema, resend the whole request_body_schema, not just the one property. Partial nested objects are the usual source of silent drops and validation errors.

A SYSTEM tool (transfer_to_number, end_call, language_detection, skip_turn, update_state, etc.) is NOT edited this way; its config lives in the agent config, so edit it via PATCH /v1/convai/agents/$AGENT_ID?branch_id=$BRANCH_ID targeting the relevant path.

architect-edit-existing-tool

1. Read the current tool first

2. Update with the full config