> ## Documentation Index
> Fetch the complete documentation index at: https://docs.verbeo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Update native tool

> Change a native tool's settings: its wording, a transfer's destination, an SMS tool's content or Twilio account. Send only the fields you are changing; saved credentials are kept when you send them back as the placeholder.

Updates a native tool in place and copies the result into the assistant's `config.nativeTools`, so the assistant shows the same settings. It never switches the tool on or off: do that with [`nativeTools`](/api-reference/assistants/update#switching-a-native-tool-on-or-off) on the assistant, or [delete the tool](/api-reference/tools/delete).

## Path parameters

<ParamField path="id" type="string" required>
  UUID of the native tool. A custom tool's id answers `404 NOT_FOUND`: change those with [Update custom tool](/api-reference/tools/update-custom).
</ParamField>

## Body

At least one field is required. A tool takes only its own settings, the ones [Create native tool](/api-reference/tools/create-native#body) lists for its name; anything else, `tool_name` included, is ignored. Every field is optional and anything you leave out is untouched.

<ParamField body="description" type="string | null">
  `null` stores an empty description.
</ParamField>

<ParamField body="transfer_call_mode" type="string">
  `transfer_call` only: `static` or `dynamic`. The tool's argument schema follows the mode. `null` is read as "not sent".
</ParamField>

<ParamField body="transfer_call_destination" type="string | null">
  `transfer_call` only. `null` clears it, which a static transfer refuses.
</ParamField>

<ParamField body="transfer_call_type" type="string">
  `transfer_call` only: `cold` or `warm`. `null` is read as "not sent".
</ParamField>

<ParamField body="sms_content_type" type="string">
  `send_sms` only: `prompt` or `static`. The tool's argument schema follows it. `null` is read as "not sent".
</ParamField>

<ParamField body="sms_static_message" type="string | null">
  `send_sms` only.
</ParamField>

<ParamField body="twilio_account_sid" type="string | null">
  `send_sms` only. `"********"`, which is what a read returns, keeps the saved one; a new SID replaces it; `null` clears it.
</ParamField>

<ParamField body="twilio_auth_token" type="string | null">
  `send_sms` only. Leave it out, or send `"********"`, to keep the saved token; a new token replaces it; `null` clears it.
</ParamField>

<ParamField body="twilio_from_number" type="string | null">
  `send_sms` only. `null` clears it.
</ParamField>

<ParamField body="timeout_seconds" type="number">
  `send_sms` only: `5`–`300`. `null` is read as "not sent".
</ParamField>

The rules that span fields are checked against the tool as it would be saved, the stored settings plus your changes. A static transfer needs a destination, a static SMS needs its message, and a Twilio SID and token are saved both or neither. So you can replace the token alone, and you remove a tool's own Twilio account by sending both as `null`:

```json theme={null}
{ "twilio_account_sid": null, "twilio_auth_token": null }
```

## Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT "https://api.verbeo.ai/v1/tool/native/5a7d1c3e-2b4f-4e6a-8c9d-0e1f2a3b4c5d" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "transfer_call_destination": "+15557654321", "transfer_call_type": "warm" }'
  ```

  ```javascript Node.js theme={null}
  const id = "5a7d1c3e-2b4f-4e6a-8c9d-0e1f2a3b4c5d";
  const res = await fetch(`https://api.verbeo.ai/v1/tool/native/${id}`, {
    method: "PUT",
    headers: {
      Authorization: `Bearer ${process.env.VERBEO_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ transfer_call_destination: "+15557654321", transfer_call_type: "warm" }),
  });
  const { data: tool } = await res.json();
  ```

  ```python Python theme={null}
  import os, requests

  tool_id = "5a7d1c3e-2b4f-4e6a-8c9d-0e1f2a3b4c5d"
  tool = requests.put(
      f"https://api.verbeo.ai/v1/tool/native/{tool_id}",
      headers={"Authorization": f"Bearer {os.environ['VERBEO_API_KEY']}"},
      json={"transfer_call_destination": "+15557654321", "transfer_call_type": "warm"},
  ).json()["data"]
  ```
</CodeGroup>

## Response

`200 OK` with the updated [tool object](/api-reference/tools/overview#the-tool-object).

```json theme={null}
{
  "success": true,
  "data": {
    "id": "5a7d1c3e-2b4f-4e6a-8c9d-0e1f2a3b4c5d",
    "tool_name": "transfer_call",
    "is_native": true,
    "transfer_call_mode": "static",
    "transfer_call_destination": "+15557654321",
    "transfer_call_type": "warm",
    "updated_at": "2026-01-23T09:12:00.456789+00:00",
    "…": "the rest of the tool object"
  }
}
```

## Errors

| Code | Status | When |
| - | - | - |
| `VALIDATION_FAILED` | 422 | `id` is not a UUID; an empty body, or one with none of this tool's settings (`No fields to update`); a malformed field; or a change that breaks a rule that spans fields: `transfer_call_destination: required for a static transfer`, `sms_static_message: required when sms_content_type is static`, `twilio_auth_token: required when twilio_account_sid is set`, or the reverse. |
| `NOT_FOUND` | 404 | No such tool, or it belongs to another workspace (`Tool not found`); or the id is a custom tool's (`Native tool not found`). |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.