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).
Path parameters
Request body
Argument values to invoke the tool with, keyed by the tool's parameter names.
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.
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.
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
Full human-readable error description when success is False. Always set on failure.
Wall-clock execution time in milliseconds.
Whether this run was a validate-only dry run.
The tool's side-effect classification (none/reads/writes/sends/unknown).
Error category: validation | timeout | runtime | connection | http_status | not_found.
Machine-readable error code: HTTP status (e.g. '404') for external API tools, or the exception class name (e.g. 'ValueError') otherwise.
Per-argument validation messages keyed by the offending field name.
Whether the result was truncated because it was too large.
The runtime variable this tool's result belongs in, read from the config that actually ran. For a tool attached by tool_id that is the saved tool's name, which the attachment does not carry — so a caller that stores the result must use this rather than reading the config it passed in. None only when the config could not be resolved at all, since naming a variable for a config that never resolved would be a guess.
Runtime variables the tool's own config asks for its result to be mapped onto — result_variable_mappings plus expand_result_into_runtime_variables. None when the config declares neither (the common case); an empty map means it declared some and none could be produced. Like the name above, these are reachable only after the by-reference merge.
The same, for mappings the tool declares with scope='workflow'. Kept separate rather than merged because they belong in a different store — the run's shared memory rather than this thread's — and a caller that wrote them to the thread instead would give each one a thread-local shadow that then wins over it everywhere. A caller with no workflow run (the Test-Tool routes) has nowhere to put these and may ignore them.
Required result mappings that could not be satisfied. The tool still SUCCEEDED — a mapping failure is a statement about the workflow's expectation of the result, not about the call — so this is populated alongside success=True and a full result.