> ## 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.

# Assign Tool to Workflow

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

Assign a catalog tool to an agent. Inserts an `inherited` workflow tool that mirrors the catalog tool's content fields and stays in sync with it on future [Update Client Tool](/docs/en/api/client-tools/update-client-tool) edits. Idempotent: re-assigning an already-assigned tool returns the existing assignment (still `200`, no duplicate row).

Both the client tool and the target agent must belong to your account.

## Path Parameters

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

## Request Body

| Field         | Type          | Required | Description                 |
| ------------- | ------------- | -------- | --------------------------- |
| `workflow_id` | string (uuid) | **Yes**  | Agent to assign the tool to |

## Responses

### `200` — Assigned (created or already existed)

```json theme={null}
{
  "success": true,
  "workflow_tool": {
    "id": "9a1b2c3d-0000-4000-8000-000000000001",
    "name": "check_subscription",
    "description": "Checks whether the lead has an active subscription",
    "url": "https://api.acme.com/subscriptions/status",
    "method": "GET",
    "timeout_ms": 10000,
    "parameters": { "type": "object", "properties": {} },
    "headers": {},
    "query_parameters": {},
    "is_active": true,
    "sort_order": 0,
    "workflow_id": "550e8400-e29b-41d4-a716-446655440000",
    "source_tool_id": "7c1b2c3d-0000-4000-8000-000000000002",
    "inherited": true,
    "auto_run_on_entry": false,
    "call_once": false,
    "available_in_statuses": null
  }
}
```

### Response Fields — WorkflowTool (public shape)

| Field                   | Type              | Description                                                                                                                 |
| ----------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `id`                    | string (uuid)     | Workflow tool identifier                                                                                                    |
| `name`                  | string            | snake\_case name, copied from the catalog tool                                                                              |
| `description`           | string            | Copied from the catalog tool, kept in sync on catalog edits                                                                 |
| `url`                   | string            | Copied from the catalog tool, kept in sync on catalog edits                                                                 |
| `method`                | string            | Copied from the catalog tool, kept in sync on catalog edits                                                                 |
| `timeout_ms`            | integer           | Copied from the catalog tool, kept in sync on catalog edits                                                                 |
| `parameters`            | object            | Copied from the catalog tool, kept in sync on catalog edits                                                                 |
| `headers`               | object            | Copied from the catalog tool, kept in sync on catalog edits                                                                 |
| `query_parameters`      | object            | Copied from the catalog tool, kept in sync on catalog edits                                                                 |
| `is_active`             | boolean           | Copied at assign time, then kept in sync on catalog edits                                                                   |
| `sort_order`            | integer           | Set fresh at assign time from the catalog tool's `sort_order`. Not synced afterwards                                        |
| `workflow_id`           | string (uuid)     | Agent this assignment belongs to                                                                                            |
| `source_tool_id`        | string (uuid)     | The catalog tool this row was assigned from                                                                                 |
| `inherited`             | boolean           | `true` for a catalog assignment (vs. a standalone [Create Workflow Tool](/docs/en/api/workflow-tools/create-workflow-tool)) |
| `auto_run_on_entry`     | boolean           | Run automatically when a lead enters an eligible status                                                                     |
| `call_once`             | boolean           | Allow only one call per lead                                                                                                |
| `available_in_statuses` | string\[] \| null | Funnel status keys where this tool is offered. `null` means every status                                                    |

This same field shape is returned by [Create Workflow Tool](/docs/en/api/workflow-tools/create-workflow-tool).

### `400` — Validation error

```json theme={null}
{
  "error": "Invalid input",
  "message": "workflow_id is required"
}
```

Also returned as `"tool id must be a valid UUID"` or `"workflow_id must be a valid UUID"`.

### `401` — Authentication error

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

### `404` — Not found

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

Also returned as `"Workflow not found"` when the agent doesn't belong to your account.

### `409` — Conflict

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

Returned when a different tool (not this catalog tool) already occupies that name in the target agent.

### `500` — Internal server error