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

# Create Tool

> Create a new tool. Tools connect to built-in integrations (e.g. Slack, OpenAPI) and are invoked automatically by your agent during calls and SMS conversations.

### Headers

**authorization** `string` *required*

Your API key for authentication.

### Body Parameters

**name** `string` *required*

The name the AI will see when deciding to use this tool. Must be at least 1 character.

Avoid names that conflict with reserved internal tools: `input`, `speak`, `transfer`, `switch`, `wait`, `finish`, `press`, `button`, `say`, `pause`, `record`, `play`, `dial`, `hang`.

**description** `string` *required*

Description of what the tool does. Shown to the AI to help it decide when to use this tool.

**integration** `string` *required*

The integration key to use. Must be one of: `bland-sms`, `custom-code`, `slack`, `salesforce`, `rest_api`, `hubspot`, `calendly`, `cal-com-v2`, `notion`.

**action** `string` *required*

The action key to invoke within the integration. To discover available action keys, call `GET /v1/integrations/{integration}/actions`. Returns `400 ACTION_NOT_FOUND` with the list of valid actions if the key is invalid.

**input\_schema** `object`

Must be a valid OpenAI function calling parameter schema. Defines the parameters the AI will fill in when invoking this tool.

```json theme={null}
{
  "type": "object",
  "properties": {
    "channel": { "type": "string" },
    "message": { "type": "string" }
  },
  "required": ["channel", "message"]
}
```

**body** `string | object`

Request body template sent to the integration. Supports prompt variables from `input_schema` (e.g. `"{{input.channel}}"`).

**speech** `string`

Text the AI says aloud while executing this tool (e.g. `"One moment while I send that message."`).

**timeout** `number`

Maximum time in milliseconds to wait for the integration to respond. Minimum `1000`, maximum `60000`.

**cache** `boolean`

Whether to cache the tool's response. Accepts `true`, `false`, `"true"`, or `"false"`.

**response\_data** `array`

Defines which fields to extract from the integration response and make available as prompt variables.

**response\_data item**

**name** `string` *required*

Variable name to assign the extracted value.

**data** `string` *required*

JSON path to the value in the response (e.g. `"$.message_id"`).

**context** `string`

Optional description of what this data represents.

**max\_retries** `number`

Number of times to retry the tool on failure. Minimum `0`, maximum `4`.

**cooldown** `number`

Seconds to wait between retries. Minimum `1`, maximum `30`.

**resource\_id** `string`

UUID of a connected resource (e.g. a Slack workspace or Salesforce org) to scope this tool to. The resource must be active and belong to your account. Returns `404` if the ID is invalid or inactive. To list available resource IDs for an integration, call `GET /v1/integrations/{integration}/resources`.

**public** `boolean`

Whether this tool is publicly visible. Defaults to `false`.

**label** `string`

Optional human-readable label for this tool.

### Response

**status** `string`

`"success"` on success, `"error"` on failure.

**data.id** `string`

The ID of the newly created tool.

**errors** `null|array`

`null` on success, or a list of error objects if the request failed.

```json Request theme={null}
{
  "name": "SendSlackMessage",
  "description": "Sends a message to a Slack channel",
  "integration": "slack",
  "action": "send_message",
  "input_schema": {
    "type": "object",
    "properties": {
      "channel": { "type": "string" },
      "message": { "type": "string" }
    },
    "required": ["channel", "message"]
  },
  "speech": "Sending that message to Slack now.",
  "timeout": 10000
}
```

```json Response (Success) theme={null}
{
  "status": "success",
  "data": {
    "id": "abc123def456"
  },
  "errors": null
}
```

```json Error (INVALID_PARAMETER) theme={null}
{
  "data": null,
  "errors": [
    {
      "code": "INVALID_PARAMETER",
      "message": "name is required"
    }
  ]
}
```

```json Error (INVALID_TOOL_TYPE) theme={null}
{
  "data": null,
  "errors": [
    {
      "code": "INVALID_TOOL_TYPE",
      "message": "The specified tool type is not supported"
    }
  ]
}
```

```json Error (INTEGRATION_NOT_FOUND) theme={null}
{
  "data": null,
  "errors": [
    {
      "code": "INTEGRATION_NOT_FOUND",
      "message": "Integration 'my_integration' is not available. Available integrations: bland-sms, custom-code, slack, salesforce, rest_api, hubspot, calendly, cal-com-v2, notion"
    }
  ]
}
```

```json Error (ACTION_NOT_FOUND) theme={null}
{
  "data": null,
  "errors": [
    {
      "code": "ACTION_NOT_FOUND",
      "message": "Action 'my_action' not found for integration 'slack'. Available actions: send_message, create_channel"
    }
  ]
}
```

```json Error (RESOURCE_NOT_FOUND) theme={null}
{
  "data": null,
  "errors": [
    {
      "code": "RESOURCE_NOT_FOUND",
      "message": "Resource not found or is inactive"
    }
  ]
}
```

***

Docs for agents: [llms.txt](https://docs.bland.ai/llms.txt)


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