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

# Create a tool

> Let your agent call your own HTTPS API during a call.

Creates a tool your agent can use mid-call, like checking stock or booking a slot. The tool is ready right away. Attach it to an agent in the dashboard: open the agent, go to **Knowledge & tools**, select the tool and save.

## Body

**name** `string` *required*

Tool name. Up to 128 characters.

**description** `string` *required*

When the agent should use this tool. Be specific, for example "Use when the customer asks if an item is in stock." Up to 2000 characters.

**url** `string` *required*

Your endpoint. Must start with `https://` and be a public address. No username or password in the URL.

**method** `string` (default: POST)

`GET`, `POST`, `PUT`, `PATCH` or `DELETE`.

**headers** `array`

Headers sent with every request. Up to 20.

**header**

**key** `string` *required*

Header name, like `X-Api-Key`.

**value** `string` *required*

Header value. Up to 4000 characters.

**secret** `boolean` (default: false)

Set `true` for API keys. Secret values are never returned. Responses show `••••••••`.

**parameters** `array`

Values the agent collects from the customer and sends. Up to 30.

**parameter**

**name** `string` *required*

Letters, numbers and underscores. Must start with a letter or underscore. Up to 64 characters.

**type** `string` (default: string)

`string`, `number` or `boolean`.

**description** `string` *required*

What the value is. The agent reads this.

**required** `boolean` (default: true)

Whether the agent must have this value before calling.

**presetParameters** `array`

Values sent every time, without asking the customer. Up to 30.

**preset**

**name** `string` *required*

Same rules as `parameters`. Names must be unique across both lists.

**type** `string` (default: string)

`string`, `number` or `boolean`.

**value** `string` *required*

Fixed text, or a placeholder: `{{call.phone_number}}` or `{{call.your_variable}}` for call details, `{{collected.field}}` for something gathered earlier in the call.

**required** `boolean` (default: true)

Whether this value must be present.

**bodyTemplate** `object`

Exact JSON body to send. Use `{{parameter_name}}` to insert a parameter, and `{{call.x}}` or `{{collected.x}}` for call details. Leave out to use the default body.

**bodyFormat** `string` (default: json)

`json` or `form`.

**timeoutMs** `number` (default: 10000)

How long to wait for your API, from `1000` to `30000`.

**speakWhileWaiting** `string`

A short line the agent says while your API runs, like "One moment, let me check." Up to 500 characters.

```bash cURL theme={null}
curl -X POST https://app.scalysis.com/api/v1/tools \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Check stock",
    "description": "Use when the customer asks if an item is in stock.",
    "url": "https://api.yourstore.com/stock",
    "method": "POST",
    "headers": [{ "key": "X-Api-Key", "value": "YOUR_STORE_KEY", "secret": true }],
    "parameters": [{ "name": "sku", "type": "string", "description": "Item code the customer mentions" }],
    "presetParameters": [{ "name": "phone", "value": "{{call.phone_number}}" }],
    "bodyTemplate": { "sku": "{{sku}}", "phone": "{{call.phone_number}}" },
    "timeoutMs": 8000,
    "speakWhileWaiting": "One moment, let me check."
  }'
```

```json 201 theme={null}
{
  "success": true,
  "action": "create_tool",
  "tool": {
    "id": 512,
    "name": "Check stock",
    "description": "Use when the customer asks if an item is in stock.",
    "method": "POST",
    "url": "https://api.yourstore.com/stock",
    "headers": [{ "key": "X-Api-Key", "value": "••••••••", "secret": true }],
    "parameters": [{ "name": "sku", "type": "string", "description": "Item code the customer mentions", "required": true }],
    "presetParameters": [{ "name": "phone", "type": "string", "value": "{{call.phone_number}}", "required": true }],
    "bodyTemplate": { "sku": "{{sku}}", "phone": "{{call.phone_number}}" },
    "bodyFormat": "json",
    "timeoutMs": 8000,
    "speakWhileWaiting": "One moment, let me check.",
    "createdAt": "2026-10-26T17:19:29.374Z",
    "updatedAt": "2026-10-26T17:19:29.374Z"
  }
}
```

```json 400 theme={null}
{
  "success": false,
  "error": "url must be a public internet address.",
  "error_code": "INVALID_REQUEST"
}
```

## Response

**tool.id** `number`

Save this. Use it to read, edit or delete the tool.

## Errors

| Status | `error_code` | Meaning |
| - | - | - |
| `400` | `INVALID_REQUEST` | A field is wrong. `error` usually says which. |
| `409` | `LIMIT_REACHED` | You have 100 tools. Delete one first. |
| `503` | `SERVICE_UNAVAILABLE` | Try again. [List tools](https://api.scalysis.com/api-reference/tools/list.md) first so you don't create it twice. |


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