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

# Tools

# Tools

Manage external tools that agents can use during calls. Tools let agents perform HTTP requests (API lookups, CRM writes, appointment booking, etc.) in real-time while on a call.

For UUID / phone / datetime formats used below, see [Data formats](/api-reference/introduction#data-formats).

## List Tools

<Endpoint method="GET" path="/api/public/v1/tools" />

### Parameters

**Query parameters:**

| Parameter | Type    | Default | Description                                       |
| --------- | ------- | ------- | ------------------------------------------------- |
| `name`    | string  | —       | Filter by name (case-insensitive substring match) |
| `limit`   | integer | `50`    | 1–100                                             |
| `offset`  | integer | `0`     | Pagination offset                                 |

Returns `data` (array of tool objects), `pagination` (`total`, `limit`, `offset`, `has_more`), and `meta`.

### cURL

```bash theme={null}
curl "https://api.truedy.ai/api/public/v1/tools" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Get Tool

<Endpoint method="GET" path="/api/public/v1/tools/{tool_id}" />

```bash theme={null}
curl "https://api.truedy.ai/api/public/v1/tools/4ee4db9b-d099-4dba-b4a8-8272a55fe25a" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Create Tool

<Endpoint method="POST" path="/api/public/v1/tools" />

### Parameters

**Request body:**

| Field                          | Type   | Required | Description                                                                                                          |
| ------------------------------ | ------ | -------- | -------------------------------------------------------------------------------------------------------------------- |
| `name`                         | string | Yes\*    | Display name for the tool                                                                                            |
| `definition`                   | object | No       | Full tool definition (see below). If omitted, a placeholder tool is created                                          |
| `definition.modelToolName`     | string | No       | Snake\_case identifier sent to the AI model. Auto-derived from `name` if omitted. Must match `^[a-zA-Z0-9_-]{1,64}$` |
| `definition.type`              | string | No       | Tool type. Use `"http"` for webhook/API integrations                                                                 |
| `definition.description`       | string | No       | Description shown to the AI model to help it decide when to use this tool                                            |
| `definition.http`              | object | No       | HTTP configuration: `url`, `method` (default `GET`)                                                                  |
| `definition.dynamicParameters` | array  | No       | Parameters the model fills dynamically at call time                                                                  |
| `definition.requirements`      | object | No       | Security options: `httpSecurityOptions` for API key auth                                                             |

\* `name` is required unless `definition.modelToolName` is explicitly provided.

**Idempotency:** Send `X-Idempotency-Key` for safe retries.

### Example — minimal

```json theme={null}
{
  "name": "Lookup Customer"
}
```

### Example — full HTTP tool

```json theme={null}
{
  "name": "Lookup Customer",
  "definition": {
    "modelToolName": "lookup_customer",
    "description": "Look up a customer by phone number to retrieve their name and account status",
    "type": "http",
    "http": {
      "url": "https://api.example.com/customer",
      "method": "GET"
    },
    "dynamicParameters": [
      {
        "name": "phone_number",
        "location": "PARAMETER_LOCATION_QUERY",
        "schema": { "type": "string", "description": "The caller's phone number in E.164 format" },
        "required": true
      }
    ]
  }
}
```

### cURL

```bash theme={null}
curl -X POST "https://api.truedy.ai/api/public/v1/tools" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: 100f451a-9f04-4d0c-8f95-87c4cb1886f4" \
  -d '{
    "name": "Lookup Customer",
    "definition": {
      "modelToolName": "lookup_customer",
      "description": "Look up a customer by phone number",
      "type": "http",
      "http": {
        "url": "https://api.example.com/customer",
        "method": "GET"
      }
    }
  }'
```

**Response:** 201 Created with `data` (tool object) and `meta`. Returns **422** if the tool definition is invalid (e.g. `modelToolName` contains invalid characters, provider error).

## Update Tool

<Endpoint method="PATCH" path="/api/public/v1/tools/{tool_id}" />

Update a tool's name and/or definition. Only included fields are changed. Changes are pushed to Ultravox immediately.

**Request body:** Any subset of `name` and/or `definition`. Returns **422** if the definition is rejected.

```bash theme={null}
curl -X PATCH "https://api.truedy.ai/api/public/v1/tools/4ee4db9b-d099-4dba-b4a8-8272a55fe25a" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Lookup Customer V2",
    "definition": {
      "http": {
        "url": "https://api.example.com/v2/customer",
        "method": "GET"
      }
    }
  }'
```

## Delete Tool

<Endpoint method="DELETE" path="/api/public/v1/tools/{tool_id}" />

Deletes the tool from Truedy and from Ultravox. Agents using this tool will no longer have access to it.

```bash theme={null}
curl -X DELETE "https://api.truedy.ai/api/public/v1/tools/4ee4db9b-d099-4dba-b4a8-8272a55fe25a" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Tool Object

| Field        | Type     | Description                                                                                        |
| ------------ | -------- | -------------------------------------------------------------------------------------------------- |
| `id`         | UUID     | Tool ID                                                                                            |
| `name`       | string   | Display name                                                                                       |
| `definition` | object   | Full tool definition including `modelToolName`, `type`, `http`, `dynamicParameters`, `description` |
| `status`     | string   | `active` — synced to Ultravox and available for use                                                |
| `created_at` | datetime | When the tool was created                                                                          |
| `updated_at` | datetime | Last updated                                                                                       |