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

# Create Workflow Tool

<span class="badge--post">POST</span> <code class="endpoint-url">/workflows/:id/tools</code>

Add a custom HTTP tool the agent can call — your own endpoint, described the way an LLM function call is described. Gate it to specific funnel stages with [Set Stage Gate](/docs/en/api/workflow-tools/set-tool-stage-gate).

## Path Parameters

| Parameter | Type          | Required | Description |
| --------- | ------------- | -------- | ----------- |
| `id`      | string (uuid) | **Yes**  | Agent ID    |

## Request Body

| Field                   | Type      | Required | Description                                                                                                     |
| ----------------------- | --------- | -------- | --------------------------------------------------------------------------------------------------------------- |
| `name`                  | string    | **Yes**  | snake\_case, matching `^[a-z][a-z0-9_]*$`. Immutable after creation                                             |
| `description`           | string    | **Yes**  | What the tool does and when the agent should call it                                                            |
| `url`                   | string    | **Yes**  | Endpoint the tool calls                                                                                         |
| `method`                | string    | No       | `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`. Default `POST`                                                      |
| `parameters`            | object    | No       | JSON-schema-style object describing the tool's call arguments. Default `{ "type": "object", "properties": {} }` |
| `headers`               | object    | No       | Static headers sent with every call, e.g. `{ "Authorization": "Bearer ..." }`                                   |
| `query_parameters`      | object    | No       | Static query string params sent with every call                                                                 |
| `timeout_ms`            | integer   | No       | Clamped to 1,000 to 120,000. Default `10000`                                                                    |
| `available_in_statuses` | string\[] | No       | Funnel status keys where this tool is offered. Omit or `null` for every status                                  |
| `auto_run_on_entry`     | boolean   | No       | Run automatically when a lead enters an eligible status. Default `false`                                        |
| `call_once`             | boolean   | No       | Allow only one call per lead. Default `false`                                                                   |
| `is_active`             | boolean   | No       | Default `true`                                                                                                  |

## Responses

### `201` — Tool created

```json theme={null}
{
  "success": true,
  "tool": {
    "id": "9a1b2c3d-0000-4000-8000-000000000001",
    "name": "check_availability",
    "description": "Checks open slots on the sales calendar for a given day",
    "method": "GET",
    "url": "https://api.acme.com/availability",
    "is_active": true,
    "available_in_statuses": null,
    "auto_run_on_entry": false,
    "call_once": false,
    "sort_order": 0
  }
}
```

### `400` — Validation error

```json theme={null}
{
  "error": "Invalid input",
  "message": "name must be snake_case (^[a-z][a-z0-9_]*$)"
}
```

Also returned as `"description is required"`, `"url is required"`, or `"method must be one of: GET, POST, PUT, PATCH, DELETE"`.

### `401` — Authentication error

See [Authentication](/docs/en/api/authentication).

### `404` — Not found

```json theme={null}
{
  "error": "Not found",
  "message": "Workflow not found"
}
```

### `409` — Conflict

```json theme={null}
{
  "error": "Conflict",
  "message": "A tool named \"check_availability\" already exists in this workflow"
}
```

### `500` — Internal server error