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

# Create mid call tool

> Create a new mid call tool

This endpoint allows you to create a new mid call tool that can be used by your AI assistants to interact with external APIs during calls.

### Body Parameters

> [!NOTE]
>
> The public API creates **HTTP request** tools. Automation Platform tools (which
> generate a linked flow) are created from the dashboard. Tool values support
> dynamic variables — use `{param}` for AI-extracted parameters in the URL, and
> `{{variable}}` (e.g. `{{customer_phone}}`) in the URL, header values, and static
> field values.

**name** `string` *required*

Tool name — letters, numbers and underscores, starting with a letter or underscore (max 64 characters, e.g., `get_weather`, `book_appointment`)

**description** `string` *required*

Detailed explanation of when and how the AI should use this tool (max 255 characters)

**endpoint** `string` *required*

Valid URL of the API endpoint to call (max 2048 characters)

**method** `string` *required*

HTTP method: `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`

**body\_format** `string`

How the request body is encoded for write methods (POST/PUT/PATCH): `json` (default) or `form` (`application/x-www-form-urlencoded`)

**timeout** `integer`

Request timeout in seconds (1-30, default: 10)

**headers** `array`

HTTP headers to send with the request

**headers properties**

**name** `string` *required*

Header name

**value** `string` *required*

Header value (max 2048 chars; supports `{{variable}}` substitution)

**static\_fields** `array`

Fixed key/value pairs always sent with the request (the AI never changes them)

**static\_fields properties**

**key** `string` *required*

Field key (max 64 chars)

**value** `string`

Field value (max 2048 chars; supports `{{variable}}` substitution)

**schema** `array`

Parameters that the AI will extract from conversation and send to the endpoint

**schema properties**

**name** `string` *required*

Parameter name (1-64 chars, must start with a letter or underscore, can contain letters, numbers and underscores)

**type** `string` *required*

Parameter type: `string`, `number`, `float`, or `boolean`

**description** `string` *required*

Description to help AI understand how to extract this parameter (3-255 chars)

**required** `boolean`

Whether the AI must collect this parameter. Optional parameters are only sent when a value was collected. Defaults to `false`.

### Response fields

**message** `string`

Success message

**data** `object`

The created tool object

**data properties**

**id** `integer`

The unique identifier of the tool

**name** `string`

The name of the tool

**description** `string`

Tool description

**type** `string`

Tool type: `http` or `automation`

**endpoint** `string`

API endpoint URL

**method** `string`

HTTP method

**body\_format** `string`

Request body encoding: `json` or `form`

**timeout** `integer`

Request timeout in seconds

**headers** `array`

HTTP headers

**static\_fields** `array`

Fixed key/value pairs always sent with the request

**schema** `array`

Parameter schema

**created\_at** `string`

ISO 8601 timestamp

**updated\_at** `string`

ISO 8601 timestamp

```json 201 Created theme={null}
{
  "message": "Tool created successfully",
  "data": {
    "id": 1,
    "name": "check_order_status",
    "description": "Use this tool to check the status of a customer's order.",
    "type": "http",
    "endpoint": "https://api.yourstore.com/orders/{order_id}/status",
    "method": "GET",
    "body_format": "json",
    "timeout": 10,
    "headers": [
      {
        "name": "Content-Type",
        "value": "application/json"
      },
      {
        "name": "Authorization",
        "value": "Bearer {{crm_key}}"
      }
    ],
    "static_fields": [
      {
        "key": "source",
        "value": "autocalls"
      },
      {
        "key": "caller",
        "value": "{{customer_phone}}"
      }
    ],
    "schema": [
      {
        "name": "order_id",
        "type": "string",
        "description": "The customer's order ID",
        "required": true
      },
      {
        "name": "amount",
        "type": "float",
        "description": "Order total as a decimal, e.g. 19.99",
        "required": false
      },
      {
        "name": "priority_order",
        "type": "boolean",
        "description": "Whether this is a priority order",
        "required": false
      }
    ],
    "created_at": "2025-10-10T12:00:00.000000Z",
    "updated_at": "2025-10-10T12:00:00.000000Z"
  }
}
```

```json 422 Validation Error theme={null}
{
  "message": "Tool name must start with a letter or underscore and contain only letters, numbers, and underscores (max 64 characters).",
  "errors": {
    "name": [
      "Tool name must start with a letter or underscore and contain only letters, numbers, and underscores (max 64 characters)."
    ]
  }
}
```

```json 422 Plan Limit Reached theme={null}
{
  "message": "You have reached your plan limit of 5 mid call tools. Please upgrade your plan to create more tools."
}
```

### Attaching Tools to Assistants

After creating a tool, you need to attach it to an assistant to use it during calls. Tools are managed through the Assistant API:

* **[Create Assistant](https://docs.receptonic.com/api-reference/assistants/create-assistant.md)** - Use the `tool_ids` parameter to attach tools when creating an assistant
* **[Update Assistant](https://docs.receptonic.com/api-reference/assistants/update-assistant.md)** - Use the `tool_ids` parameter to add, remove, or replace tools on an existing assistant


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