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

<ParamField header="authorization" type="string" required>
  Your API key for authentication.
</ParamField>

### Body Parameters

<ParamField body="name" type="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`.
</ParamField>

<ParamField body="description" type="string" required>
  Description of what the tool does. Shown to the AI to help it decide when to use this tool.
</ParamField>

<ParamField body="integration" type="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`.
</ParamField>

<ParamField body="action" type="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.
</ParamField>

<ParamField body="input_schema" type="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"]
  }
  ```
</ParamField>

<ParamField body="body" type="string | object">
  Request body template sent to the integration. Supports prompt variables from `input_schema` (e.g. `"{{input.channel}}"`).
</ParamField>

<ParamField body="speech" type="string">
  Text the AI says aloud while executing this tool (e.g. `"One moment while I send that message."`).
</ParamField>

<ParamField body="timeout" type="number">
  Maximum time in milliseconds to wait for the integration to respond. Minimum `1000`, maximum `60000`.
</ParamField>

<ParamField body="cache" type="boolean">
  Whether to cache the tool's response. Accepts `true`, `false`, `"true"`, or `"false"`.
</ParamField>

<ParamField body="response_data" type="array">
  Defines which fields to extract from the integration response and make available as prompt variables.

  <Expandable title="response_data item">
    <ParamField body="name" type="string" required>
      Variable name to assign the extracted value.
    </ParamField>

    <ParamField body="data" type="string" required>
      JSON path to the value in the response (e.g. `"$.message_id"`).
    </ParamField>

    <ParamField body="context" type="string">
      Optional description of what this data represents.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="max_retries" type="number">
  Number of times to retry the tool on failure. Minimum `0`, maximum `4`.
</ParamField>

<ParamField body="cooldown" type="number">
  Seconds to wait between retries. Minimum `1`, maximum `30`.
</ParamField>

<ParamField body="resource_id" type="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`.
</ParamField>

<ParamField body="public" type="boolean">
  Whether this tool is publicly visible. Defaults to `false`.
</ParamField>

<ParamField body="label" type="string">
  Optional human-readable label for this tool.
</ParamField>

### Response

<ResponseField name="status" type="string">
  `"success"` on success, `"error"` on failure.
</ResponseField>

<ResponseField name="data.id" type="string">
  The ID of the newly created tool.
</ResponseField>

<ResponseField name="errors" type="null|array">
  `null` on success, or a list of error objects if the request failed.
</ResponseField>

<ResponseExample>
  ```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"
      }
    ]
  }
  ```
</ResponseExample>

***

Docs for agents: [llms.txt](/llms.txt)