curl --request POST \ --url https://realtime-api.voiceflow.com/v1/stable/tool \ --header 'Authorization: Bearer <token>' --header 'Content-Type: application/json' \ --data '{ "description": "<string>", "target": { "global": true, "playbookID": "<string>" }, "messages": null, "captureInputVariables": {}, "asyncExecution": false, "inputVariables": {}, "captureResponse": {}, "type": "api", "apiToolID": "<string>" }'

{ "tool": { "id": "<string>", "createdAt": "2026-09-10T00:00:00.000Z", "updatedAt": "2026-09-10T00:00:00.000Z", "messages": "<AgentToolMessages>", "description": "<string>", "captureInputVariables": {}, "type": "api", "apiToolID": "<string>", "asyncExecution": true, "inputVariables": {}, "captureResponse": {} } }

Authorizations

Authorization

string

header

required

Voiceflow bearer token

Query Parameters

projectID

string

required

The ID of the project to operate on.

environmentAlias

string

required

The alias of the environment to operate on (e.g. main).

Body

Show child attributes

Option 1

Show child attributes

description

string

A description of what the tool does, used by the agent to decide when to call it.

target

object

required

Show child attributes

global

boolean

Target the agent. Cannot be used with playbookID.

playbookID

string

Target a specific playbook. Cannot be used with global.

messages

object

Show child attributes

generative

object

Show child attributes

delay

object

object · 2 attributes: enabled, examples

failure

object

object · 2 attributes: enabled, examples

execution

object

object · 2 attributes: enabled, examples

completion

object

object · 2 attributes: enabled, examples

delayMessageID

string

required

failureMessageID

string

required

executionMessageID

string

required

completionMessageID

string

required

delayMessageSeconds

number

required

captureInputVariables

object

A map of tool input names to the variables or entities whose values are captured into them.

asyncExecution

boolean

default:false

When enabled, the tool runs in the background without blocking the conversation.

inputVariables

object

captureResponse

object

A map of variable names to the parts of the tool response captured into them.

type

enum<string>

required

Discriminator indicating this tool executes a saved API request.

Available options: api

apiToolID

string

required

The ID of the API resource this tool executes.

Option 2

Show child attributes

description

string

A description of what the tool does, used by the agent to decide when to call it.

target

object

required

StableToolTarget — see its attributes above

messages

object

Show child attributes

generative

object

Show child attributes

delay

object

object · 2 attributes: enabled, examples

failure

object

object · 2 attributes: enabled, examples

execution

object

object · 2 attributes: enabled, examples

completion

object

object · 2 attributes: enabled, examples

delayMessageID

string

required

failureMessageID

string

required

executionMessageID

string

required

completionMessageID

string

required

delayMessageSeconds

number

required

captureInputVariables

object

A map of tool input names to the variables or entities whose values are captured into them.

asyncExecution

boolean

default:false

When enabled, the tool runs in the background without blocking the conversation.

inputVariables

object

captureResponse

object

A map of variable names to the parts of the tool response captured into them.

type

enum<string>

required

Discriminator indicating this tool executes a custom function.

Available options: function

functionID

string

required

The ID of the function resource this tool executes.

Option 3

Show child attributes

description

string

A description of what the tool does, used by the agent to decide when to call it.

target

object

required

StableToolTarget — see its attributes above

messages

object

Show child attributes

generative

object

Show child attributes

delay

object

object · 2 attributes: enabled, examples

failure

object

object · 2 attributes: enabled, examples

execution

object

object · 2 attributes: enabled, examples

completion

object

object · 2 attributes: enabled, examples

delayMessageID

string

required

failureMessageID

string

required

executionMessageID

string

required

completionMessageID

string

required

delayMessageSeconds

number

required

captureInputVariables

object

A map of tool input names to the variables or entities whose values are captured into them.

inputVariables

object

captureResponse

object

A map of variable names to the parts of the tool response captured into them.

type

enum<string>

required

Discriminator indicating this tool calls a tool from an MCP server.

Available options: mcp

mcpToolID

string

required

The ID of the MCP tool resource this tool calls.

Option 4

Show child attributes

description

string

A description of what the tool does, used by the agent to decide when to call it.

target

object

required

StableToolTarget — see its attributes above

messages

object

Show child attributes

generative

object

Show child attributes

delay

object

object · 2 attributes: enabled, examples

failure

object

object · 2 attributes: enabled, examples

execution

object

object · 2 attributes: enabled, examples

completion

object

object · 2 attributes: enabled, examples

delayMessageID

string

required

failureMessageID

string

required

executionMessageID

string

required

completionMessageID

string

required

delayMessageSeconds

number

required

captureInputVariables

object

A map of tool input names to the variables or entities whose values are captured into them.

inputVariables

object

captureResponse

object

A map of variable names to the parts of the tool response captured into them.

type

enum<string>

required

Discriminator indicating this tool calls a connected first-party integration.

Available options: integration

integrationToolID

string

required

The ID of the integration tool resource this tool calls.

Response

201 - application/json

Attaches an existing API tool, function, or MCP tool to the agent or to a playbook, and returns the attachment with its generated ID and wiring. The underlying resource is referenced by ID and is not created here.

tool

object

required

Show child attributes

Option 1

Show child attributes

string

required

createdAt

string

required

updatedAt

string

required

messages

object

required

Show child attributes

generative

object

object · 4 attributes: delay, failure, execution, completion

delayMessageID

string

required

failureMessageID

string

required

executionMessageID

string

required

completionMessageID

string

required

delayMessageSeconds

number

required

description

string

required

A description of what the tool does, used by the agent to decide when to call it.

captureInputVariables

object

required

A map of tool input names to the variables or entities whose values are captured into them.

type

enum<string>

required

Discriminator indicating this tool executes a saved API request.

Available options: api

apiToolID

string

required

The ID of the API resource this tool executes.

asyncExecution

boolean

required

When enabled, the tool runs in the background without blocking the conversation.

inputVariables

object

required

A map of input names to the values the agent supplies when calling the tool.

captureResponse

object

required

A map of variable names to the parts of the tool response captured into them.

Option 2

Show child attributes

string

required

createdAt

string

required

updatedAt

string

required

messages

object

required

Show child attributes

generative

object

object · 4 attributes: delay, failure, execution, completion

delayMessageID

string

required

failureMessageID

string

required

executionMessageID

string

required

completionMessageID

string

required

delayMessageSeconds

number

required

description

string

required

A description of what the tool does, used by the agent to decide when to call it.

captureInputVariables

object

required

A map of tool input names to the variables or entities whose values are captured into them.

type

enum<string>

required

Discriminator indicating this tool executes a custom function.

Available options: function

functionID

string

required

The ID of the function resource this tool executes.

asyncExecution

boolean

required

When enabled, the tool runs in the background without blocking the conversation.

inputVariables

object

required

A map of input names to the values the agent supplies when calling the tool.

captureResponse

object

required

A map of variable names to the parts of the tool response captured into them.

Option 3

Show child attributes

string

required

createdAt

string

required

updatedAt

string

required

messages

object

required

Show child attributes

generative

object

object · 4 attributes: delay, failure, execution, completion

delayMessageID

string

required

failureMessageID

string

required

executionMessageID

string

required

completionMessageID

string

required

delayMessageSeconds

number

required

description

string

required

A description of what the tool does, used by the agent to decide when to call it.

captureInputVariables

object

required

A map of tool input names to the variables or entities whose values are captured into them.

type

enum<string>

required

Discriminator indicating this tool calls a tool from an MCP server.

Available options: mcp

mcpToolID

string

required

The ID of the MCP tool resource this tool calls.

inputVariables

object

required

A map of input names to the values the agent supplies when calling the tool.

captureResponse

object

required

A map of variable names to the parts of the tool response captured into them.

Option 4

Show child attributes

string

required

createdAt

string

required

updatedAt

string

required

messages

object

required

Show child attributes

generative

object

object · 4 attributes: delay, failure, execution, completion

delayMessageID

string

required

failureMessageID

string

required

executionMessageID

string

required

completionMessageID

string

required

delayMessageSeconds

number

required

description

string

required

A description of what the tool does, used by the agent to decide when to call it.

captureInputVariables

object

required

A map of tool input names to the variables or entities whose values are captured into them.

type

enum<string>

required

Discriminator indicating this tool calls a connected first-party integration.

Available options: integration

integrationToolID

string

required

The ID of the integration tool resource this tool calls.

inputVariables

object

required

A map of input names to the values the agent supplies when calling the tool.

captureResponse

object

required

A map of variable names to the parts of the tool response captured into them.

Getting started

Running agents

Build

Manage

Publishing

Observe

Insights

QA

Analytics

Webhooks

Create tool

Authorizations

Query Parameters

Body

Response

Getting started

Running agents

Build

Manage

Publishing

Observe

Insights

QA

Analytics

Webhooks