Skip to main content
POST
/
agent
/
tool
/
{agent_id}
Create/Update Tool
curl --request POST \
  --url https://api.getoutbox.ai/agent/tool/{agent_id} \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "id": "<string>",
  "description": "<string>",
  "url": "<string>",
  "method": "POST",
  "type": "custom",
  "builtin_key": "send_sms",
  "mcp_tool": "<string>",
  "auth_token": "<string>",
  "is_async": false,
  "is_success": false,
  "is_prerun": false,
  "is_postrun": false,
  "config": {},
  "messages": [
    {
      "type": "request",
      "content": "<string>"
    }
  ],
  "schema": [
    {
      "id": "<string>",
      "name": "<string>",
      "description": "<string>",
      "type": "<string>",
      "required": true
    }
  ]
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "type": "<string>",
  "builtin_key": "<string>",
  "display_name": "<string>",
  "mcp_tool": "<string>",
  "url": "<string>",
  "description": "<string>",
  "method": "<string>",
  "auth_token": "<string>",
  "config": {},
  "is_async": true,
  "is_success": true,
  "is_prerun": true,
  "is_postrun": true,
  "schema": [
    {
      "id": "<string>",
      "name": "<string>",
      "description": "<string>",
      "type": "<string>",
      "required": true
    }
  ],
  "destinations": [
    {}
  ],
  "mcp_config_id": "<string>",
  "mcp_allowed_tools": [
    "<string>"
  ],
  "mcp_toolkit": "<string>",
  "icon_url": "<string>",
  "application_icon_url": "<string>"
}

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.

​
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. 
{
  "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.

Authorizations

​
Authorization
string
header
required

Company API Key

Path Parameters

​
agent_id
string
required

The ID of the agent

Body

application/json

Tool configuration

​
name
string
required

Tool name

​
id
string

Tool ID (for updating existing tool)

​
description
string

Tool description

​
url
string

API endpoint URL

​
method
string
default:POST

HTTP method

​
type
string
default:custom

Tool type. Use builtin to attach an Outbox-native built-in tool.

​
builtin_key
enum<string>

Built-in tool key. Required when type is builtin.

Available options:
send_sms,
send_email,
create_opportunity,
update_opportunity,
update_contact,
add_tag,
remove_tag,
add_to_workflow,
remove_from_workflow,
book_ai_callback
​
mcp_tool
string

MCP tool identifier

​
auth_token
string

Authentication token

​
is_async
boolean
default:false

Async execution flag

​
is_success
boolean
default:false

When true, a successful run of this tool marks the conversation as successful

​
is_prerun
boolean
default:false

Run this tool before the conversation starts

​
is_postrun
boolean
default:false

Run this tool after the conversation ends

​
config
object

Preset tool inputs so the agent does not need to supply them

​
messages
object[]
​
schema
object[]

Response

Tool created/updated successfully

​
id
string<uuid>
​
name
string
​
type
string

custom, builtin, mcp, transfer, etc.

​
builtin_key
string | null

Built-in tool key (builtin tools only).

​
display_name
string | null

Resolved display name for built-in or MCP tools.

​
mcp_tool
string | null

MCP tool identifier (mcp tools only).

​
url
string | null
​
description
string | null
​
method
string | null

HTTP method (custom tools).

​
auth_token
string | null
​
config
object

Preset tool inputs supplied by the developer.

​
is_async
boolean
​
is_success
boolean
​
is_prerun
boolean
​
is_postrun
boolean
​
schema
object[]

Tool input variables.

​
destinations
object[]

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*.

​
mcp_config_id
string | null

Composio MCP server ID (mcp tools only).

​
mcp_allowed_tools
string[]

Allowed-tool whitelist for MCP servers.

​
mcp_toolkit
string | null
​
icon_url
string | null

Application icon URL (mcp tools only).

​
application_icon_url
string | null

Application icon URL for resolved tool metadata.