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

# Create/Update Tool

> Create or update a tool for an agent

## Attach a Built-In Tool

Built-in tools are attached after an agent is created. Set `type` to `builtin` and pass the tool's `builtin_key`.

```json theme={null}
{
  "type": "builtin",
  "builtin_key": "send_sms",
  "name": "send_sms",
  "description": "Send an SMS to the current contact.",
  "config": {},
  "is_success": false,
  "is_prerun": false,
  "is_postrun": false
}
```

`config` can pre-fill tool inputs so the agent does not need to supply them. When `is_success` is `true`, a successful run of this tool marks the conversation as successful.


## OpenAPI

````yaml POST /agent/tool/{agent_id}
openapi: 3.1.0
info:
  title: Outbox AI API
  description: API for managing AI agents (chatbots and voicebots) on the Outbox platform
  version: 1.0.0
servers:
  - url: https://api.getoutbox.ai
security: []
paths:
  /agent/tool/{agent_id}:
    post:
      summary: Create/Update Tool
      description: Create or update a tool for an agent
      parameters:
        - name: agent_id
          in: path
          description: The ID of the agent
          required: true
          schema:
            type: string
      requestBody:
        description: Tool configuration
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ToolCreate'
      responses:
        '200':
          description: Tool created/updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolSimple'
        '400':
          description: Bad Request - Missing required fields
        '401':
          description: Unauthorized - Invalid or missing API key
        '403':
          description: Forbidden - Insufficient permissions (requires level 2)
        '404':
          description: Agent not found
      security:
        - CompanyApiKey: []
components:
  schemas:
    ToolCreate:
      type: object
      required:
        - name
      properties:
        id:
          type: string
          description: Tool ID (for updating existing tool)
        name:
          type: string
          description: Tool name
        description:
          type: string
          description: Tool description
        url:
          type: string
          description: API endpoint URL
        method:
          type: string
          default: POST
          description: HTTP method
        type:
          type: string
          default: custom
          description: Tool type. Use `builtin` to attach an Outbox-native built-in tool.
        builtin_key:
          type: string
          enum:
            - send_sms
            - send_email
            - create_opportunity
            - update_opportunity
            - update_contact
            - add_tag
            - remove_tag
            - add_to_workflow
            - remove_from_workflow
            - book_ai_callback
          description: Built-in tool key. Required when `type` is `builtin`.
        mcp_tool:
          type: string
          description: MCP tool identifier
        auth_token:
          type: string
          description: Authentication token
        is_async:
          type: boolean
          default: false
          description: Async execution flag
        is_success:
          type: boolean
          default: false
          description: >-
            When true, a successful run of this tool marks the conversation as
            successful
        is_prerun:
          type: boolean
          default: false
          description: Run this tool before the conversation starts
        is_postrun:
          type: boolean
          default: false
          description: Run this tool after the conversation ends
        config:
          type: object
          additionalProperties: true
          description: Preset tool inputs so the agent does not need to supply them
        messages:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                  - request
                  - response
              content:
                type: string
        schema:
          type: array
          items:
            $ref: '#/components/schemas/ToolParameter'
    ToolSimple:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        type:
          type: string
          description: '`custom`, `builtin`, `mcp`, `transfer`, etc.'
        builtin_key:
          type: string
          nullable: true
          description: Built-in tool key (builtin tools only).
        display_name:
          type: string
          nullable: true
          description: Resolved display name for built-in or MCP tools.
        mcp_tool:
          type: string
          nullable: true
          description: MCP tool identifier (mcp tools only).
        url:
          type: string
          nullable: true
        description:
          type: string
          nullable: true
        method:
          type: string
          nullable: true
          description: HTTP method (custom tools).
        auth_token:
          type: string
          nullable: true
        config:
          type: object
          additionalProperties: true
          description: Preset tool inputs supplied by the developer.
        is_async:
          type: boolean
        is_success:
          type: boolean
        is_prerun:
          type: boolean
        is_postrun:
          type: boolean
        schema:
          type: array
          description: Tool input variables.
          items:
            $ref: '#/components/schemas/ToolParameter'
        destinations:
          type: array
          description: >-
            Transfer destinations (transfer tools only). Each entry: id,
            phone_number, description, transfer_message, transfer_type, plus
            optional `custom_message`, `fallback_message`, `extension`,
            `transfer_agent_prompt`, `assistant_first_message*`.
          items:
            type: object
        mcp_config_id:
          type: string
          nullable: true
          description: Composio MCP server ID (mcp tools only).
        mcp_allowed_tools:
          type: array
          items:
            type: string
          description: Allowed-tool whitelist for MCP servers.
        mcp_toolkit:
          type: string
          nullable: true
        icon_url:
          type: string
          nullable: true
          description: Application icon URL (mcp tools only).
        application_icon_url:
          type: string
          nullable: true
          description: Application icon URL for resolved tool metadata.
    ToolParameter:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        type:
          type: string
        required:
          type: boolean
  securitySchemes:
    CompanyApiKey:
      type: apiKey
      in: header
      name: Authorization
      description: Company API Key

````