{"id":8612,"plugin_id":"plugin_asdk_app_6a8d784b60cc81919aeafbfaeda5fbcf","kind":"skill","collection_source":null,"comparison_source":null,"observed_at":"2026-09-30T22:53:12.483Z","digest":"ceb97e4de091084cd6bab5c3890d3aa2d27dd2c38f10a97d9a6e71d932dc08e2","against":null,"payload":{"name":"architect-edit-existing-tool","description":"Use when the user wants to change an existing tool on their agent (rename it, fix its description, change a webhook URL/headers/auth, add or edit a request-body parameter or response assignment, adjust the timeout, or flip a client tool's expects_response / execution mode), or when a tool edit won't save or throws schema_mismatch / validation / not_found.","included_files":[],"skill_md_contents":"---\nname: architect-edit-existing-tool\ndescription: Use when the user wants to change an existing tool on their agent (rename it, fix its description, change a webhook URL/headers/auth, add or edit a request-body parameter or response assignment, adjust the timeout, or flip a client tool's expects_response / execution mode), or when a tool edit won't save or throws schema_mismatch / validation / not_found.\n---\n\nEditing 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`.\n\n## 1. Read the current tool first\n\nDo not edit blind; the failures come from patching a shape you never read.\n\n- `GET /v1/convai/tools` to get the exact tool id and its TYPE (webhook / client / code). The type determines the config shape.\n- `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`.\n- `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.\n\n## 2. Update with the full config\n\n```\nPATCH /v1/convai/tools/{tool_id}\n```\n\n`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.\n\nA 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.\n\n## 3. Schema gotchas\n\nWebhook / code tools (`request_body_schema`):\n\n- 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`.\n- Array properties REQUIRE an `items` schema and MUST NOT carry `constant_value`.\n- URLs must be STATIC, no `{{variables}}` in the path; move dynamic values into `request_body_schema`.\n- `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.\n- Response `assignments` use dot-notation `value_path` (`data.items.0.id`, NOT `data.items[0].id`; bracket indexing silently returns null).\n- `response_timeout_secs`: default 20, max 120.\n\nClient tools:\n\n- `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.\n- Parameters follow the same one-of-four value-source rule.\n\nAll types:\n\n- 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.\n- Do not invent new schema keys.\n\n## 4. Recovery\n\n- `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.\n- `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.\n- `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.\n\n## 5. Follow-ups\n\nIf 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.\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}