architect-edit-existing-tool

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.

3. Schema gotchas

Webhook / code tools (request_body_schema):

• Each property needs EXACTLY ONE of: a non-empty description, constant_value, dynamic_variable, or is_system_provided. Two (or zero) is a validation error. When editing, do not leave the old dynamic_variable while adding a description.
• Array properties REQUIRE an items schema and MUST NOT carry constant_value.
• URLs must be STATIC, no {{variables}} in the path; move dynamic values into request_body_schema.
• request_headers is an OBJECT, not an array. For secrets use {"secret_id": "..."} (list via GET /v1/convai/secrets); do not paste a raw key when the original used a secret id.
• Response assignments use dot-notation value_path (data.items.0.id, NOT data.items[0].id; bracket indexing silently returns null).
• response_timeout_secs: default 20, max 120.

Client tools:

• expects_response (bool) and execution_mode (immediate / post_tool_speech / async) are the two fields people edit and get wrong. If execution_mode is async, the tool is fire-and-forget and expects_response must be false.
• Parameters follow the same one-of-four value-source rule.

All types:

• Renaming: the tool name is referenced by the LLM and by any node prompts or edge conditions that call it by name. After a rename, prompts still using the old name will not fire the tool. Flag this and offer to update the referencing prompts in the same pass via the agent config.
• Do not invent new schema keys.

4. Recovery

• schema_mismatch: the patch shape does not match. Re-GET the tool, diff against what you sent, and resend the full nested object for the field you touched. Do not retry the identical body.
• validation: a per-field rule above was broken (two-of-four on a property, array with constant_value, async + expects_response, timeout > 120, {{var}} in URL). Fix that field and resend.
• not_found: a stale or wrong tool id, or the tool is not on this branch. Re-GET /v1/convai/tools for the current agent/branch and use the exact id.

5. Follow-ups

If you renamed the tool or changed its parameters, update referencing node prompts or edge conditions via PATCH /v1/convai/agents/$AGENT_ID?branch_id=$BRANCH_ID, and re-check any tool test that targeted the old schema (a sim test edit is delete + recreate; see the create-tool-test skill). If the underlying problem is that the tool is not being CALLED or returns no result at runtime (not a config-edit failure), use the troubleshoot-tool-errors skill instead.