dry_run, which validates and returns the would-be outcome without applying it.
Tool index
Each tool name links to its section below.| Tool | Class | What it does |
|---|---|---|
list_runs | Read | Recent job runs with status, timing, and last error. |
get_run | Read | One run’s fields plus an output count and a redacted log tail. |
explain_job_failure | Read | A failed run’s primary error, detected error patterns, log tail, and next steps. |
list_schedules | Read | Schedules with cadence, status, target packages, and run timestamps. |
get_schedule | Read | One schedule’s full config, target packages with variables, and run metadata. |
toggle_schedule | Write | Enable or disable a schedule. |
create_schedule | Write | Create a schedule (disabled by default) that runs packages on a cadence. |
update_schedule | Write | Change a schedule’s cadence or metadata, toggle it, or append packages. |
run_package | Write | Start a new run of a package on a cluster. |
cancel_job | Write | Stop an in-flight run. |
retry_job | Write | Re-run a finished run as a new sibling run. |
Run inspection
list_runs
Read-only. Lists recent job runs (executions) in the account, most recent first. Each run is one execution of a package. Defaults to root runs only, so child retries are excluded. Filter bypackage_id or status.
Maximum runs to return. 1 to 200.
Number of runs to skip, for paging.
Restrict to runs of a single package.
Filter by run status. One of
idle, pending, queued, running, completed, failed, stopped.Each run includes
id, package_id, status, owner_id, cluster_id, started_at, completed_at, failed_at, runtime_seconds, progress, attempts, created_at, updated_at, and last_error (present for failed or stopped runs, with sensitive values redacted).offset, limit, and returned (the number of runs on this page).get_run
Read-only. Returns details for a single run by id: the same fields aslist_runs, plus an output count and a redacted tail of the execution log for inline diagnosis. Run variables are deliberately not exposed.
The run to fetch.
How many trailing log lines to return. 1 to 200.
The run id, alongside
package_id, status, owner_id, cluster_id, started_at, completed_at, failed_at, runtime_seconds, progress, attempts, created_at, updated_at, and last_error (for failed or stopped runs, redacted).Number of outputs the run produced.
The last N lines of the execution log, redacted.
null when no log body exists.explain_job_failure
Read-only. Diagnoses a failed run without an LLM call on the server. Returns the run’s primary error, programmatically detected error patterns (FATAL, ERROR, exception, connection, auth, schema, and more), a redacted log tail, and heuristic next-step suggestions. The calling agent does the final synthesis.The run to diagnose.
How many trailing log lines to return. 1 to 200.
The run id, with
package_id, status, and failed_at.The run’s primary error message (from
last_error), redacted. null for runs that did not fail or stop.Structured error patterns found in the log, each with a
type such as connection_failure, auth_failure, schema_error, destination_conflict, rate_limited, out_of_memory, or exception.The redacted trailing log lines, with
log_lines_returned and log_truncated alongside.Heuristic next steps tied to the detected patterns (for example, run
test_connection on a refused connection, or discover_schema on a schema mismatch).Schedules
list_schedules
Read-only. Lists schedules in the account. Each schedule fires on a cron expression or an interval. Filter bypackage_id (schedules targeting a given package) or status.
Maximum schedules to return. 1 to 200.
Number of schedules to skip, for paging.
Filter by schedule status. One of
enabled, disabled.Return only schedules whose task targets this package.
Each schedule includes
id, name, description, status, schedule_type, schedule_expression, interval_amount, interval_unit, cron_time_zone, start_at, end_at, next_run_at, last_run_at, last_run_status, execution_count, recurrence_count, package_ids, owner_id, created_at, and updated_at.offset, limit, and returned.get_schedule
Read-only. Returns full details for a single schedule by id, including the packages it targets with their per-package variables, the task config, and run metadata.The schedule to fetch.
The schedule id, with
name, description, status, schedule_type, schedule_expression, interval_amount, interval_unit, cron_time_zone, start_at, end_at, owner_id, execution_count, recurrence_count, next_run_at, last_run_at, last_run_id, last_run_status, auto_retry, auto_retry_attempts, created_at, and updated_at.Each target package as
{ package_id, package_name, variables }.Task config:
nodes, terminate_on_idle, time_to_idle, and reuse_cluster_strategy.toggle_schedule
Mutation. Enables or disables an existing schedule. This is a pure metadata change: no credentials, no data writes, no cluster spin-up, and it is reversible by the same tool. The cron worker picks up the new state within about 60 seconds. Idempotent in both directions, an already-matching state returnsalready_in_target_state: true as a no-op. Supports dry_run, which returns the would-be transition without toggling.
The schedule to toggle.
true to enable, false to disable.The schedule id, with
previous_status, new_status, already_in_target_state, and toggled_at.create_schedule
Mutation. Creates a schedule that runs one or more packages on a cadence. It is created disabled by default, so an agent call will not silently start firing recurring jobs. Passstatus: "enabled" (or call toggle_schedule afterward) to activate it. Supports dry_run, which validates and returns the would-be schedule without creating it.
Schedule name. Max 255 characters.
Cadence type. One of
interval, cron.ISO-8601 timestamp for when the schedule starts. Interpreted as UTC unless
current_time_zone is set.At least one package. Each item may be
{ package_id, variables? } or a bare package id.For
interval schedules: how many interval_unit between runs. Minimum 1.For
interval schedules: minutes, hours, days, weeks, or months.For
cron schedules: the cron expression, for example 0 9 * * *.Initial status. One of
enabled, disabled.The new schedule id, with
name, status, schedule_type, and next_run_at. On a dry_run, these are nested under would_create with a valid flag (and errors when invalid).update_schedule
Mutation. Updates an existing schedule’s cadence or metadata, toggles it, and/or appends packages. Only the fields you pass are changed.status goes through the proper enable/disable transition. add_packages only appends to the schedule’s package list: packages already on the schedule are skipped, and nothing is removed or reordered. To change the full package set, recreate the schedule. Supports dry_run.
The schedule to update.
Packages to add. Each item may be
{ package_id, variables? } or a bare package id. Appends only.Change the schedule status through the enable/disable transition. One of
enabled, disabled.Change the cadence type. One of
interval, cron.New ISO-8601 start timestamp.
The schedule id, with
name, status, schedule_type, next_run_at, and package_ids. On a dry_run, the response is nested under would_update with the changed fields, target status, and add_packages.Execution and recovery
run_package
Mutation. Starts a new run of a package on a given cluster and returns therun_id immediately, with the run in pending. It does not wait for completion: poll get_run for status. Compute charged for time the run was already executing on the cluster cannot be refunded, so cancel via cancel_job if needed. Supports dry_run, which returns the predicted state without creating a run.
The package to run. Must not be archived.
The cluster to dispatch to. Must not be terminated or terminating.
A map of variable name to value that overrides the package’s defaults for this run only. String literals must be wrapped in inner single quotes (pass
"'Smith'", not "Smith"), since $variable references are evaluated as Pig expressions. Numbers and booleans need no quoting, and values are matched case-sensitively.The new run id, with
package_id, package_name, cluster_id, status, variables_applied (the overridden keys), and started_at. On a dry_run, the details are nested under would_create with a cluster_action hint.cancel_job
Mutation. Stops an in-flight run by sending the cancel signal through the run’s state machine. Anidle run stops synchronously; pending, queued, or running runs move to pending_stoppage and are stopped asynchronously (poll get_run to confirm). Idempotent: a run already cancelling returns already_cancelling: true, and a run already finished returns already_terminal: true. Not reversible once cancelled. Supports dry_run.
The run to cancel.
The run id, with
previous_status, new_status, already_terminal, already_cancelling, and cancel_requested_at (the time the cancel signal was sent, not when the run finished stopping). On a dry_run, the details are nested under would_cancel with a cluster_impact hint.retry_job
Mutation. Re-runs a finished (failed, cancelled, or completed) run by creating a fresh run that copies the parent’s package, cluster, and variables, then starts it. The new run is a sibling: the original run is preserved in its terminal status. By default,variables are merged onto the parent’s; pass replace_variables: true to use only the new hash. Supports dry_run, which returns the resolved variable set without creating the run.
The parent run to re-run.
Variable overrides. Merged onto the parent’s variables by default (override wins on collision). Omit to retry exactly as the parent ran.
When
true, use only the supplied variables hash instead of merging onto the parent’s.The new run id, with
parent_run_id, package_id, cluster_id, status, variables_applied, and started_at. On a dry_run, the details are nested under would_retry with the fully variables_resolved hash.