@spec __tool__() :: map()

Defines the run_workflow tool specification including its name, description, and input JSON schema.

The returned map describes a tool named "run_workflow" and a provider-compatible parameters schema for workflow inputs. The schema accepts either a concrete steps array (each step requires id and task), a Skill-backed template_id plus optional template_args, or separate skill and template fields. Optional workflow-level fields include: id, name, max_concurrency, and timeout_ms. Each concrete step object may include agent, depends_on, permission_mode, workspace_mode, read_set, write_set, and an optional per-step timeout_ms.

Keep shape alternatives in descriptions and runtime validation rather than top-level JSON Schema composition keywords; the OpenAI Responses API rejects those at the tool schema root.

@spec dry_run(map(), map()) :: {:ok, map()} | {:error, any()}

Validates and plans a workflow without executing its steps.

Performs a dry-run of the provided workflow arguments and returns a human-readable summary plus the planner's raw workflow result.

Parameters

• args: Map representing the workflow specification (steps, optional id/name, concurrency/timeout settings, etc.).
• context: Execution context used to build planner options (workspace, provider, permission and agent/skill options, depth).

@returns {:ok, response} where response is a map containing:

• "dry_run" => true
• "output": a summary string describing the validation/plan
• "workflow": the planner's raw result map. On failure, returns {:error, reason} as returned by the workflow planner.

@spec execute(map(), map()) :: {:ok, map()} | {:error, term()}

Runs a workflow described by args under the provided context and returns a human-readable summary together with the raw workflow result.

On success returns {:ok, %{"output" => summary, "workflow" => result}} where summary is a formatted completion string and result is the workflow result map. On failure returns {:error, reason} propagated from the workflow runner.