v5

latestOpenAPI 3.1.02026-07-31129337684.6 KB

Tools

Execute Tool

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

post/workflows/v1/tools/{tool_id}/execute

Path parameters

tool_idstring required

Example:5eb7cf5a86d9755df3a6c593

Request body

argsobject

Argument values to invoke the tool with, keyed by the tool's parameter names.

dry_runboolean

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_variablesobject

Test values for {{dynamic}} placeholders in the tool config (endpoint/headers/body/code). Resolved before execution to mirror the live workflow runtime.

runtime_variablesobject

Test values for [[runtime]] placeholders in the tool config (endpoint/headers/body/code). Resolved before execution to mirror the live workflow runtime.

Response

Successful Response

successboolean required

{"stackTrail":"components:schemas:ToolExecuteResponse:properties:result:anyOf","oasType":"schema","type":"unknown","title":"Result","description":"The tool's return value on success.","nullable":true}

errorstring nullable

Full human-readable error description when success is False. Always set on failure.

latency_msinteger nullable

Wall-clock execution time in milliseconds.

dry_runboolean

Whether this run was a validate-only dry run.

side_effectstring nullable

The tool's side-effect classification (none/reads/writes/sends/unknown).

error_typestring nullable

error_codestring nullable

Machine-readable error code: HTTP status (e.g. '404') for external API tools, or the exception class name (e.g. 'ValueError') otherwise.

field_errorsobject nullable

Per-argument validation messages keyed by the offending field name.

truncatedboolean

Whether the result was truncated because it was too large.