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

# Run tools without a conversation

> Execute a saved function, API tool, integration action, or MCP tool through REST, CLI, or Voiceflow MCP.

## What you will accomplish

Run one tool with explicit inputs and inspect its result without compiling an agent or starting a conversation. This uses the selected environment’s saved **draft**, not a published release. Calls to external services are real; use a test account for actions that send messages or change records.

## Before you begin

Choose a project and environment you can access. Save the function or API tool, connect the MCP server, or connect the integration in Voiceflow. You need the resource’s read permission for schema discovery and execute permission to run it.

For REST, follow [API authentication](/docs/api-reference/authentication). For CLI, use an authenticated CLI release with `execute` and `get-schema` commands (the reference is generated from v0.287.0). For an AI client, follow [MCP setup](/docs/mcp/overview).

## Discover, execute, and inspect

<Steps>
<Step title="Choose the capability">
Use a function for custom JavaScript, an API tool for a saved HTTP request, an integration action for a connected service, or an MCP tool for a tool on a connected server. Integration actions use the project’s Draft connection and their catalog tool name; they do not need to be attached to the agent first.


| Capability | CLI reference | MCP reference |
| --- | --- | --- |
| Function | [Execute a function](/docs/cli/commands/function/execute) | [Function operations](/docs/mcp/execution/function) |
| API tool | [Execute an API tool](/docs/cli/commands/api-tool/execute) | [API tool operations](/docs/mcp/execution/api-tool) |
| Integration | [Execute an integration action](/docs/cli/commands/integration/execute) | [Integration operations](/docs/mcp/execution/integration) |
| MCP tool | [Execute an MCP tool](/docs/cli/commands/mcp-tool/execute) | [MCP tool operations](/docs/mcp/execution/mcp-tool) |

</Step>
<Step title="Discover the inputs">
Call the resource’s schema operation before execution. For a function:

```sh
vf function get-schema --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" --function-id "$FUNCTION_ID"
```

Functions and API tools require a string value for every declared input and reject unknown names. Integration and MCP inputs follow their schemas. Supply actual values rather than conversation-variable tokens. A project secret can be supplied as `{secret_name}`; see [input and secret rules](/docs/developers/tools/execution-behavior).
</Step>
<Step title="Run the saved draft">
For a function whose schema declares a string input named `customer_id`, use:

```sh
vf function execute --project-id "$PROJECT_ID" --environment-alias "$ENVIRONMENT" --function-id "$FUNCTION_ID" --inputs '{"customer_id":"test-customer"}'
```

This input name is illustrative: replace it with your function’s declared inputs. The equivalent REST request is:

```sh
curl --request POST "https://realtime-api.voiceflow.com/v1/stable/function/$FUNCTION_ID/execute?projectID=$PROJECT_ID&environmentAlias=$ENVIRONMENT" \
  --header "Authorization: Bearer $VF_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"inputs":{"customer_id":"test-customer"}}'
```

Use your deployment’s API base URL from the API reference. To use an AI client, ask it to discover the function schema and execute with these explicit inputs. The [function MCP reference](/docs/mcp/execution/function) shows the structured invocation.
</Step>
<Step title="Read the result">
Check `success`, `error`, and `truncated`, then inspect `output`. A function returns output variables, its selected path, and traces. An API tool returns the upstream HTTP status, headers, and body. Integration and MCP tools return their tool result. An HTTP 200 response can still contain `success: false`.
</Step>
</Steps>

## Verify the outcome

Compare the output with the expected result for your test inputs. For an external action, confirm the effect once in the receiving system. Direct execution does not verify agent routing or conversation state: attach the tool, compile, and run a conversation separately when testing how the agent uses it.

## Troubleshooting

<a id="inputs-are-rejected"></a>

<Accordion title="Inputs are rejected">

Read the schema again after editing the tool. For functions and API tools, include every declared input, omit unknown names, and supply strings. Replace conversation-variable placeholders with explicit values.

</Accordion>

<a id="credentials-or-secrets-are-missing"></a>

<Accordion title="Credentials or secrets are missing">

Check the project, environment, saved server authorization, and Draft integration connection. Use project-secret names rather than copying credentials into inputs. Nested JSON values do not receive secret substitution.

</Accordion>

<a id="the-request-succeeds-but-the-tool-fails"></a>

<Accordion title="The request succeeds but the tool fails">

Inspect `success` and `error` in the result as well as the transport status. MCP tools can report their own error within a successful protocol response.

</Accordion>

<a id="execution-times-out"></a>

<Accordion title="Execution times out">

Check the external system before retrying an action. A timeout does not establish that the action stopped. See [limits and failure handling](/docs/developers/tools/execution-behavior).

</Accordion>

<a id="the-runtime-needs-an-update"></a>

<Accordion title="The runtime needs an update">

A 503 stating that execution requires a general-runtime update means this deployment does not yet expose the execution route. Contact your deployment administrator; changing inputs will not resolve it.

</Accordion>