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

# Create a tool

> Create a reusable tool for agents in the workspace.

Requires Editor, Admin, or Owner. Choose a typed `definition` for an HTTP API, end call, transfer call, calculator, or MCP tool. The request schema lists the configuration for each type.

Tools with a stored credential, nonempty headers, or preset parameter values additionally require Admin or Owner. MCP configuration can contact the configured server to discover tools. Creating a tool does not automatically attach it to an agent. Each successful request creates another resource.

Tools managed by an integration cannot be created, edited, duplicated, archived, or restored through the general tool endpoints; these attempts return `409`. Do not set `integration_provider` or `integration_id` yourself. Manage Calendly access through its [connection endpoints](https://docs.agents.labs.bandwidth.com/api-reference/calendly/status.md).


## OpenAPI

````yaml POST /api/v1/tools/
openapi: 3.1.0
info:
  title: Bandwidth Agent Builder API
  version: v1
  description: >-
    Manage agents, place calls, and retrieve conversation results in your
    workspace.
servers:
  - url: https://agents.labs.bandwidth.com
    description: Workspace API
security: []
paths:
  /api/v1/tools/:
    post:
      tags:
        - tools
      summary: Create a tool
      description: >-
        **Authorization:** Requires an Editor, Admin, or Owner role in the
        requested workspace.


        Create a reusable tool for agents in the workspace.
      operationId: create_tool_api_v1_tools__post
      parameters:
        - description: >-
            Required with X-BW-LABS-AGENTS-API-KEY: the positive local workspace
            ID to access. The key owner must be a current member. Missing or
            invalid IDs return 400; non-member workspaces return 403. Not
            required for bearer authentication, which uses the user's selected
            workspace.
          in: header
          name: X-VOAI-ORGANIZATION-ID
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              Required with X-BW-LABS-AGENTS-API-KEY: the positive local
              workspace ID to access. The key owner must be a current member.
              Missing or invalid IDs return 400; non-member workspaces return
              403. Not required for bearer authentication, which uses the user's
              selected workspace.
            title: X-Voai-Organization-Id
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateToolRequest'
            example:
              name: Lookup order
              category: http_api
              definition:
                type: http_api
                config:
                  method: GET
                  url: https://api.example.com/orders
                  timeout_ms: 5000
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolResponse'
          description: Successful Response
        '400':
          description: Invalid request or missing/invalid workspace header with an API key.
        '401':
          description: Missing, invalid, or expired credential.
        '403':
          description: >-
            The account lacks access to the workspace, resource, or required
            role.
        '404':
          description: Not found
        '409':
          description: >-
            Managed integration tools must be created through their source
            integration.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
        - LabsAuth: []
        - LabsApiKey: []
components:
  schemas:
    CreateToolRequest:
      properties:
        category:
          default: http_api
          enum:
            - http_api
            - end_call
            - transfer_call
            - calculator
            - native
            - integration
            - mcp
          title: Category
          type: string
        definition:
          discriminator:
            mapping:
              calculator: '#/components/schemas/CalculatorToolDefinition'
              end_call: '#/components/schemas/EndCallToolDefinition'
              http_api: '#/components/schemas/HttpApiToolDefinition'
              mcp: '#/components/schemas/McpToolDefinition'
              transfer_call: '#/components/schemas/TransferCallToolDefinition'
            propertyName: type
          oneOf:
            - $ref: '#/components/schemas/HttpApiToolDefinition'
            - $ref: '#/components/schemas/EndCallToolDefinition'
            - $ref: '#/components/schemas/TransferCallToolDefinition'
            - $ref: '#/components/schemas/CalculatorToolDefinition'
            - $ref: '#/components/schemas/McpToolDefinition'
          title: Definition
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        icon:
          anyOf:
            - maxLength: 50
              type: string
            - type: 'null'
          default: globe
          title: Icon
        icon_color:
          anyOf:
            - maxLength: 7
              type: string
            - type: 'null'
          default: '#3B82F6'
          title: Icon Color
        name:
          maxLength: 255
          title: Name
          type: string
      required:
        - name
        - definition
      title: CreateToolRequest
      type: object
    ToolResponse:
      properties:
        category:
          title: Category
          type: string
        created_at:
          format: date-time
          title: Created At
          type: string
        created_by:
          anyOf:
            - $ref: '#/components/schemas/CreatedByResponse'
            - type: 'null'
        definition:
          additionalProperties: true
          title: Definition
          type: object
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        icon:
          anyOf:
            - type: string
            - type: 'null'
          title: Icon
        icon_color:
          anyOf:
            - type: string
            - type: 'null'
          title: Icon Color
        id:
          title: Id
          type: integer
        name:
          title: Name
          type: string
        status:
          title: Status
          type: string
        tool_uuid:
          title: Tool Uuid
          type: string
        updated_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Updated At
      required:
        - id
        - tool_uuid
        - name
        - description
        - category
        - icon
        - icon_color
        - status
        - definition
        - created_at
        - updated_at
      title: ToolResponse
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    CalculatorToolDefinition:
      properties:
        schema_version:
          default: 1
          title: Schema Version
          type: integer
        type:
          const: calculator
          title: Type
          type: string
      required:
        - type
      title: CalculatorToolDefinition
      type: object
    EndCallToolDefinition:
      properties:
        config:
          $ref: '#/components/schemas/EndCallConfig'
        schema_version:
          default: 1
          title: Schema Version
          type: integer
        type:
          const: end_call
          title: Type
          type: string
      required:
        - type
        - config
      title: EndCallToolDefinition
      type: object
    HttpApiToolDefinition:
      properties:
        config:
          $ref: '#/components/schemas/HttpApiConfig'
        schema_version:
          default: 1
          title: Schema Version
          type: integer
        type:
          const: http_api
          title: Type
          type: string
      required:
        - type
        - config
      title: HttpApiToolDefinition
      type: object
    McpToolDefinition:
      properties:
        config:
          $ref: '#/components/schemas/McpToolConfig'
        schema_version:
          default: 1
          title: Schema Version
          type: integer
        type:
          const: mcp
          title: Type
          type: string
      required:
        - type
        - config
      title: McpToolDefinition
      type: object
    TransferCallToolDefinition:
      properties:
        config:
          $ref: '#/components/schemas/TransferCallConfig'
        schema_version:
          default: 1
          title: Schema Version
          type: integer
        type:
          const: transfer_call
          title: Type
          type: string
      required:
        - type
        - config
      title: TransferCallToolDefinition
      type: object
    CreatedByResponse:
      properties:
        id:
          title: Id
          type: integer
        provider_id:
          title: Provider Id
          type: string
      required:
        - id
        - provider_id
      title: CreatedByResponse
      type: object
    ValidationError:
      properties:
        ctx:
          title: Context
          type: object
        input:
          title: Input
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
        - loc
        - msg
        - type
      title: ValidationError
      type: object
    EndCallConfig:
      properties:
        audioRecordingId:
          anyOf:
            - type: string
            - type: 'null'
          title: Audiorecordingid
        customMessage:
          anyOf:
            - type: string
            - type: 'null'
          title: Custommessage
        endCallReason:
          default: false
          title: Endcallreason
          type: boolean
        endCallReasonDescription:
          anyOf:
            - type: string
            - type: 'null'
          title: Endcallreasondescription
        messageType:
          default: none
          enum:
            - none
            - custom
            - audio
          title: Messagetype
          type: string
      title: EndCallConfig
      type: object
    HttpApiConfig:
      properties:
        credential_uuid:
          anyOf:
            - type: string
            - type: 'null'
          title: Credential Uuid
        customMessage:
          anyOf:
            - type: string
            - type: 'null'
          title: Custommessage
        customMessageRecordingId:
          anyOf:
            - type: string
            - type: 'null'
          title: Custommessagerecordingid
        customMessageType:
          anyOf:
            - enum:
                - text
                - audio
              type: string
            - type: 'null'
          title: Custommessagetype
        headers:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          title: Headers
        method:
          enum:
            - GET
            - POST
            - PUT
            - PATCH
            - DELETE
          title: Method
          type: string
        parameters:
          anyOf:
            - items:
                $ref: '#/components/schemas/ToolParameter'
              type: array
            - type: 'null'
          title: Parameters
        preset_parameters:
          anyOf:
            - items:
                $ref: '#/components/schemas/PresetToolParameter'
              type: array
            - type: 'null'
          title: Preset Parameters
        timeout_ms:
          anyOf:
            - minimum: 1
              type: integer
            - type: 'null'
          default: 5000
          title: Timeout Ms
        url:
          title: Url
          type: string
      required:
        - method
        - url
      title: HttpApiConfig
      type: object
    McpToolConfig:
      properties:
        account_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Account Name
          description: Connected account display name for a managed integration.
        credential_uuid:
          anyOf:
            - type: string
            - type: 'null'
          title: Credential Uuid
        discovered_tools:
          items:
            additionalProperties: true
            type: object
          title: Discovered Tools
          type: array
        integration_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Integration Id
          description: >-
            Server-managed source integration identifier. Use the integration
            connection APIs rather than setting this during tool creation or
            update.
        integration_provider:
          anyOf:
            - type: string
            - type: 'null'
          title: Integration Provider
          description: >-
            Server-managed source integration provider. Use the integration
            connection APIs rather than setting this during tool creation or
            update.
        sse_read_timeout_secs:
          default: 300
          minimum: 0
          title: Sse Read Timeout Secs
          type: integer
        timeout_secs:
          default: 30
          minimum: 0
          title: Timeout Secs
          type: integer
        tools_filter:
          items:
            type: string
          title: Tools Filter
          type: array
        transport:
          const: streamable_http
          default: streamable_http
          title: Transport
          type: string
        url:
          title: Url
          type: string
      required:
        - url
      title: McpToolConfig
      type: object
    TransferCallConfig:
      properties:
        audioRecordingId:
          anyOf:
            - type: string
            - type: 'null'
          title: Audiorecordingid
        customMessage:
          anyOf:
            - type: string
            - type: 'null'
          title: Custommessage
        destination:
          title: Destination
          type: string
        messageType:
          default: none
          enum:
            - none
            - custom
            - audio
          title: Messagetype
          type: string
        timeout:
          default: 30
          maximum: 120
          minimum: 5
          title: Timeout
          type: integer
      required:
        - destination
      title: TransferCallConfig
      type: object
    ToolParameter:
      properties:
        description:
          title: Description
          type: string
        name:
          title: Name
          type: string
        required:
          default: true
          title: Required
          type: boolean
        type:
          enum:
            - string
            - number
            - boolean
            - object
            - array
          title: Type
          type: string
      required:
        - name
        - type
        - description
      title: ToolParameter
      type: object
    PresetToolParameter:
      properties:
        name:
          title: Name
          type: string
        required:
          default: true
          title: Required
          type: boolean
        type:
          enum:
            - string
            - number
            - boolean
            - object
            - array
          title: Type
          type: string
        value_template:
          title: Value Template
          type: string
      required:
        - name
        - type
        - value_template
      title: PresetToolParameter
      type: object
  securitySchemes:
    LabsAuth:
      description: >-
        Bandwidth Labs OAuth access token. Uses the user's selected workspace;
        the workspace header is not required. Do not also send an API key.
        Bearer-only operations may additionally require the Labs `super_user`
        role.
      scheme: bearer
      type: http
    LabsApiKey:
      description: >-
        Bandwidth Labs API key. Also send `X-VOAI-ORGANIZATION-ID` with a
        positive local workspace ID belonging to the key owner. Access follows
        the owner's current workspace role. Do not also send a bearer token. API
        keys cannot access bearer-only or Labs `super_user` operations.
      in: header
      name: X-BW-LABS-AGENTS-API-KEY
      type: apiKey

````

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