create_tool. Requires Editor, Admin, or Owner in the applicable workspace and a connected OAuth session.
Creates an HTTP API, end-call, transfer-call, calculator, or MCP tool from the typed request. Use an existing credential_uuid from list_credentials for authentication; create secrets in the console. Tools with stored credentials, headers, or preset values additionally require Admin or Owner. MCP creation can discover the remote server’s catalog.
Inspect created, tool_uuid, and failure fields. Possible errors include validation_error, credential_not_found, credential_admin_required, and placeholder_not_allowed. A created tool is not automatically attached to an agent; reference its UUID in the agent definition.
Integration-managed tool groups cannot be created with this tool. Do not set integration_provider or integration_id: the request returns managed_integration_tool. For Calendly, use the connection endpoints and then select the discovered tools for each agent.
Arguments
| Name | Type | Required | Defaults and limits |
|---|---|---|---|
request | object | Yes | See full schema |
Example arguments
Replace sample resource IDs with IDs returned in your selected workspace.{
"request": {
"name": "Lookup order",
"category": "http_api",
"definition": {
"type": "http_api",
"config": {
"method": "GET",
"url": "https://api.example.com/orders"
}
}
}
}
Result and errors
The schema below describes MCPstructuredContent, including the result wrapper where present. Your client may also display a text representation. Read success flags and structured errors before continuing; transport success alone does not prove the operation succeeded. Authentication, missing membership, and insufficient role can fail before a tool result is produced. See troubleshooting.
Effect: Changes state. Retry: Do not blindly repeat successful calls. Discovery annotations describe behavior; they do not grant permission or replace confirmation for consequential actions.
Input schema
Input schema
{
"additionalProperties": false,
"properties": {
"request": {
"properties": {
"category": {
"default": "http_api",
"enum": [
"http_api",
"end_call",
"transfer_call",
"calculator",
"native",
"integration",
"mcp"
],
"type": "string"
},
"definition": {
"oneOf": [
{
"properties": {
"config": {
"properties": {
"credential_uuid": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"customMessage": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"customMessageRecordingId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"customMessageType": {
"anyOf": [
{
"enum": [
"text",
"audio"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"default": null
},
"method": {
"enum": [
"GET",
"POST",
"PUT",
"PATCH",
"DELETE"
],
"type": "string"
},
"parameters": {
"anyOf": [
{
"items": {
"properties": {
"description": {
"type": "string"
},
"name": {
"type": "string"
},
"required": {
"default": true,
"type": "boolean"
},
"type": {
"enum": [
"string",
"number",
"boolean",
"object",
"array"
],
"type": "string"
}
},
"required": [
"name",
"type",
"description"
],
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"preset_parameters": {
"anyOf": [
{
"items": {
"properties": {
"name": {
"type": "string"
},
"required": {
"default": true,
"type": "boolean"
},
"type": {
"enum": [
"string",
"number",
"boolean",
"object",
"array"
],
"type": "string"
},
"value_template": {
"type": "string"
}
},
"required": [
"name",
"type",
"value_template"
],
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null
},
"timeout_ms": {
"anyOf": [
{
"minimum": 1,
"type": "integer"
},
{
"type": "null"
}
],
"default": 5000
},
"url": {
"type": "string"
}
},
"required": [
"method",
"url"
],
"type": "object"
},
"schema_version": {
"default": 1,
"type": "integer"
},
"type": {
"const": "http_api",
"type": "string"
}
},
"required": [
"type",
"config"
],
"type": "object"
},
{
"properties": {
"config": {
"properties": {
"audioRecordingId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"customMessage": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"endCallReason": {
"default": false,
"type": "boolean"
},
"endCallReasonDescription": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"messageType": {
"default": "none",
"enum": [
"none",
"custom",
"audio"
],
"type": "string"
}
},
"type": "object"
},
"schema_version": {
"default": 1,
"type": "integer"
},
"type": {
"const": "end_call",
"type": "string"
}
},
"required": [
"type",
"config"
],
"type": "object"
},
{
"properties": {
"config": {
"properties": {
"audioRecordingId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"customMessage": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"destination": {
"type": "string"
},
"messageType": {
"default": "none",
"enum": [
"none",
"custom",
"audio"
],
"type": "string"
},
"timeout": {
"default": 30,
"maximum": 120,
"minimum": 5,
"type": "integer"
}
},
"required": [
"destination"
],
"type": "object"
},
"schema_version": {
"default": 1,
"type": "integer"
},
"type": {
"const": "transfer_call",
"type": "string"
}
},
"required": [
"type",
"config"
],
"type": "object"
},
{
"properties": {
"schema_version": {
"default": 1,
"type": "integer"
},
"type": {
"const": "calculator",
"type": "string"
}
},
"required": [
"type"
],
"type": "object"
},
{
"properties": {
"config": {
"properties": {
"account_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"credential_uuid": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"discovered_tools": {
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
"integration_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"integration_provider": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"sse_read_timeout_secs": {
"default": 300,
"minimum": 0,
"type": "integer"
},
"timeout_secs": {
"default": 30,
"minimum": 0,
"type": "integer"
},
"tools_filter": {
"items": {
"type": "string"
},
"type": "array"
},
"transport": {
"const": "streamable_http",
"default": "streamable_http",
"type": "string"
},
"url": {
"type": "string"
}
},
"required": [
"url"
],
"type": "object"
},
"schema_version": {
"default": 1,
"type": "integer"
},
"type": {
"const": "mcp",
"type": "string"
}
},
"required": [
"type",
"config"
],
"type": "object"
}
]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
},
"icon": {
"anyOf": [
{
"maxLength": 50,
"type": "string"
},
{
"type": "null"
}
],
"default": "globe"
},
"icon_color": {
"anyOf": [
{
"maxLength": 7,
"type": "string"
},
{
"type": "null"
}
],
"default": "#3B82F6"
},
"name": {
"maxLength": 255,
"type": "string"
}
},
"required": [
"name",
"definition"
],
"type": "object"
}
},
"required": [
"request"
],
"type": "object"
}
Result schema
Result schema
{
"properties": {
"result": {
"anyOf": [
{
"properties": {
"category": {
"type": "string"
},
"created": {
"const": true,
"type": "boolean"
},
"definition": {
"additionalProperties": true,
"type": "object"
},
"name": {
"type": "string"
},
"status": {
"enum": [
"active",
"archived",
"draft"
],
"type": "string"
},
"tool_uuid": {
"type": "string"
}
},
"required": [
"created",
"tool_uuid",
"name",
"category",
"status",
"definition"
],
"type": "object"
},
{
"properties": {
"created": {
"const": false,
"type": "boolean"
},
"error": {
"type": "string"
},
"error_code": {
"type": "string"
}
},
"required": [
"created",
"error_code",
"error"
],
"type": "object"
}
]
}
},
"required": [
"result"
],
"type": "object"
}