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

# Create tool

> Create a new mid-call tool that assistants can call during conversations.

Creates a new mid-call tool. After creation, attach the tool to one or more assistants using the `tool_ids` parameter.

## Endpoint

`POST /user/tools`

## Request

<ParamField body="name" type="string" required>
  Tool name. Must contain only lowercase letters and underscores, and start with a letter (e.g., `get_weather`, `book_appointment`).
</ParamField>

<ParamField body="description" type="string" required>
  Description of when and how the AI should use this tool. Maximum 255 characters. This description is passed to the AI model.
</ParamField>

<ParamField body="endpoint" type="string" required>
  Valid URL of the API endpoint to call.
</ParamField>

<ParamField body="method" type="string" required>
  HTTP method: `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`.
</ParamField>

<ParamField body="timeout" type="integer" default="10">
  Request timeout in seconds. Range: 1–30.
</ParamField>

<ParamField body="headers" type="array">
  HTTP headers to send with the request.

  <Expandable title="Header properties">
    <ParamField body="name" type="string" required>Header name.</ParamField>
    <ParamField body="value" type="string" required>Header value.</ParamField>
  </Expandable>
</ParamField>

<ParamField body="schema" type="array">
  Parameters the AI extracts from the conversation and sends to the endpoint.

  <Expandable title="Schema field properties">
    <ParamField body="name" type="string" required>
      Parameter name. 2–32 characters, must start with a letter, letters and underscores only.
    </ParamField>

    <ParamField body="type" type="string" required>
      Parameter type: `string`, `number`, or `boolean`.
    </ParamField>

    <ParamField body="description" type="string" required>
      Description to help the AI extract this parameter. 3–255 characters.
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="message" type="string">Confirmation message.</ResponseField>

<ResponseField name="data" type="object">
  The created tool.

  <Expandable title="properties">
    <ResponseField name="id" type="integer">Unique identifier of the tool.</ResponseField>
    <ResponseField name="name" type="string">Tool name.</ResponseField>
    <ResponseField name="description" type="string">Tool description.</ResponseField>
    <ResponseField name="endpoint" type="string">API endpoint URL.</ResponseField>
    <ResponseField name="method" type="string">HTTP method.</ResponseField>
    <ResponseField name="timeout" type="integer">Request timeout in seconds.</ResponseField>
    <ResponseField name="headers" type="array">HTTP headers.</ResponseField>
    <ResponseField name="schema" type="array">Parameter schema.</ResponseField>
    <ResponseField name="created_at" type="string">ISO 8601 creation timestamp.</ResponseField>
    <ResponseField name="updated_at" type="string">ISO 8601 last update timestamp.</ResponseField>
  </Expandable>
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://portal.intellixent.ai/api/user/tools" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "check_order_status",
      "description": "Use this tool to check the status of a customer order when they ask about it.",
      "endpoint": "https://api.yourstore.com/orders/status",
      "method": "GET",
      "timeout": 10,
      "headers": [
        {"name": "Authorization", "value": "Bearer sk_..."}
      ],
      "schema": [
        {
          "name": "order_id",
          "type": "string",
          "description": "The customer order ID to check"
        }
      ]
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://portal.intellixent.ai/api/user/tools', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'check_order_status',
      description: "Use this tool to check the status of a customer order when they ask about it.",
      endpoint: 'https://api.yourstore.com/orders/status',
      method: 'GET',
      timeout: 10,
      headers: [{ name: 'Authorization', value: 'Bearer sk_...' }],
      schema: [
        { name: 'order_id', type: 'string', description: 'The customer order ID to check' }
      ]
    })
  });

  const data = await response.json();
  console.log(data.data.id); // New tool ID
  ```
</CodeGroup>

```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 order when they ask about it.",
    "endpoint": "https://api.yourstore.com/orders/status",
    "method": "GET",
    "timeout": 10,
    "headers": [
      { "name": "Authorization", "value": "Bearer sk_..." }
    ],
    "schema": [
      {
        "name": "order_id",
        "type": "string",
        "description": "The customer order ID to check"
      }
    ],
    "created_at": "2025-10-10T12:00:00.000000Z",
    "updated_at": "2025-10-10T12:00:00.000000Z"
  }
}
```

```json 422 Invalid name format theme={null}
{
  "message": "The name field must contain only lowercase letters and underscores, and start with a letter.",
  "errors": {
    "name": ["Tool name must contain only lowercase letters and underscores, and start with a letter."]
  }
}
```

After creating a tool, attach it to an assistant using the `tool_ids` parameter in [Create assistant](/api-reference/assistants/create-assistant) or [Update assistant](/api-reference/assistants/update-assistant).