---
title: "Execute Tool"
method: POST
path: "/workflows/v1/tools/{tool_id}/execute"
tags: ["Tools"]
---

# Execute Tool

`POST /workflows/v1/tools/{tool_id}/execute`

Execute a saved custom tool against the supplied argument values and return its output.

Runtime failures are returned as HTTP 200 with ``success=False`` and a clean ``error`` message
(see :func:`execute_tool_inline`).

## Path parameters

- `tool_id` string, required

## Request body

- ToolExecuteRequest
  - `args` object — Argument values to invoke the tool with, keyed by the tool's parameter names.
  - `dry_run` boolean — When True, side-effecting tools (writes/sends/unknown) are validated but NOT executed - no external effect occurs and a simulated result is returned. Pure/read-only tools run normally.
  - `dynamic_variables` object — Test values for {{dynamic}} placeholders in the tool config (endpoint/headers/body/code). Resolved before execution to mirror the live workflow runtime. The team's global variables are applied automatically, exactly as the live runtime does; values supplied here override them.
  - `runtime_variables` object — Test values for [[runtime]] placeholders in the tool config (endpoint/headers/body/code). Resolved before execution to mirror the live workflow runtime.

## Response `200`

Successful Response

- ToolExecuteResponse
  - `success` boolean, required
  - `result` unknown
  - `error` string, nullable — Full human-readable error description when success is False. Always set on failure.
  - `latency_ms` integer, nullable — Wall-clock execution time in milliseconds.
  - `dry_run` boolean — Whether this run was a validate-only dry run.
  - `side_effect` string, nullable — The tool's side-effect classification (none/reads/writes/sends/unknown).
  - `error_type` string, nullable — Error category: validation | timeout | runtime | connection | http_status | not_found.
  - `error_code` string, nullable — Machine-readable error code: HTTP status (e.g. '404') for external API tools, or the exception class name (e.g. 'ValueError') otherwise.
  - `field_errors` object, nullable — Per-argument validation messages keyed by the offending field name.
  - `truncated` boolean — Whether the result was truncated because it was too large.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/interactly/apis/interactly-api-3.md) · [All operations](https://skmtc.net/interactly/apis/interactly-api-3/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/interactly/interactly-api-3/versions/9f4e7dc7e094/schema)