Job and schedule tools

Work that runs to completion: one-off jobs, their runs, and the schedules that create them.

Permission is what the tool server requires before it dispatches; who holds it is read from the control plane’s own grant. The two are read from different places on purpose: a tool server that grants more than the control plane does offers an operation and then has it refused halfway through a conversation.

Advertised says whether the tool appears in the default tool list. Most do not: a small window is advertised and the rest are found with search_tools, read with describe_tool and invoked with request_tool. A tool reached that way is checked against the same permission as a direct call.

Generated from Tool. Hand edits to this table are overwritten on the next build — change the Go doc comment, or the generator.

Tool	Permission	Who holds it	Advertised
cronjob_create	cronjobs:create	operator	no
cronjob_delete	cronjobs:delete	operator	no
cronjob_get	cronjobs:read	developer, operator, readonly, support	no
cronjob_list	cronjobs:read	developer, operator, readonly, support	no
cronjob_resume	cronjobs:update	operator	no
cronjob_suspend	cronjobs:update	operator	no
cronjob_update	cronjobs:update	operator	no
job_create	jobs:create	operator	no
job_delete	jobs:delete	operator	no
job_get	jobs:read	developer, operator, readonly, support	no
job_list	jobs:read	developer, operator, readonly, support	no
job_rerun	jobs:run	operator	no
job_runs	jobs:read	developer, operator, readonly, support	no
job_update	jobs:update	operator	no

cronjob_create

Create a scheduled workload — a job that the platform runs on a cron schedule. The CronJob owns one managed job of the same name and re-runs it on every firing, so run history accumulates under one name rather than fragmenting. This is additive only: an existing name is refused with 409. For a one-off run, use job_create instead.

Argument	Type	Required	Meaning
name	string	yes	CronJob name — lowercase alphanumeric with hyphens, max 63 characters. Must not already exist.
schedule	—	yes	—
timezone	—	no	—
suspend	boolean	no	Create it suspended (stored but never firing). Set it running later with cronjob_update.
concurrencyPolicy	—	no	—
startingDeadlineSeconds	—	no	—
jobTemplate	object	yes	What each firing runs — a job spec without a name, since the CronJob owns the name. Requires at least an image.

It also accepts the fields of the deployment description itself, shared with the control plane’s own schema rather than restated here — see the deployment manifest reference. Two fields the manifest accepts are deliberately absent from this tool: inline secret material, because anything typed into a conversation is in the transcript for good, and the mount path, which the control plane refuses.

cronjob_delete

Delete a CronJob. THIS CASCADES: it destroys the schedule, the managed job it owns, and that job’s entire run history — every record of every past firing. If the intent is only to stop it firing, use cronjob_update with suspend=true instead, which is reversible and keeps the history. Requires confirm=true.

Argument	Type	Required	Meaning
name	string	yes	CronJob name to delete
confirm	boolean	yes	Must be true to proceed. Deleting a CronJob also deletes its managed job and every run record.

cronjob_get

Get the full stored spec of one CronJob: its schedule, timezone, concurrency policy, the job template it runs, and the controller’s own record of when it last fired and last succeeded.

Argument	Type	Required	Meaning
name	string	yes	CronJob name

cronjob_list

List scheduled workloads (CronJobs) with their schedule, whether they are suspended, and when they last fired. Use format=‘summary’ (default) for minimal output or ‘full’ for the complete stored spec.

Argument	Type	Required	Meaning
suspended_only	boolean	no	Only return schedules that are currently suspended (not firing).
format	one of summary, standard, full	no	Response detail level: ‘summary’ (name/schedule/suspended), ‘standard’ (adds image, last fire time and missed firings), ‘full’ (complete stored spec). Default: summary.

cronjob_resume

Resume a suspended scheduled workload: future firings start happening again on its existing schedule. Firings missed while it was suspended are not replayed beyond the schedule’s own catch-up window.

Argument	Type	Required	Meaning
name	string	yes	CronJob name to resume

cronjob_suspend

Suspend a scheduled workload: stop all future firings while keeping the schedule, the job and its entire run history. Fully reversible with cronjob_resume. Safe to apply at any moment, including mid-run — a suspended schedule performs no schedule evaluation at all, and a run already in flight is left alone. This is the correct way to take a schedule out of service; cronjob_delete is not.

Argument	Type	Required	Meaning
name	string	yes	CronJob name to suspend

cronjob_update

Change a stored CronJob — its schedule, timezone, concurrency policy, history limits, or the job template each firing runs. Also the way to SUSPEND a schedule (suspend: true) or resume it (suspend: false): suspending stops all future firings, changes nothing that is already running, and is fully reversible — it is the safe way to take a schedule out of service without losing its history. Anything you do not send is kept as stored. ONE EXCEPTION WORTH KNOWING: secret references in the job template are UNIONED with what is already stored, so omitting one never removes it — send an explicit empty list to clear them.

Argument	Type	Required	Meaning
name	string	yes	CronJob name to update
schedule	—	no	—
timezone	—	no	—
suspend	boolean	no	true stops all future firings (reversible, and safe to apply mid-run — a suspended schedule performs no evaluation at all); false resumes them.
concurrencyPolicy	—	no	—
startingDeadlineSeconds	—	no	—
jobTemplate	object	no	Changes to what each firing runs. Fields you send replace the stored ones; fields you omit are kept. Note that maps (environment, labels) replace outright rather than merging — send the full desired map.

It also accepts the fields of the deployment description itself, shared with the control plane’s own schema rather than restated here — see the deployment manifest reference. Two fields the manifest accepts are deliberately absent from this tool: inline secret material, because anything typed into a conversation is in the transcript for good, and the mount path, which the control plane refuses.

job_create

Create a run-to-completion Job — a workload that runs once and stops (migration, seed, one-shot import). Creating it queues it: the job starts as soon as the controller places it. This is additive only: an existing name is refused with 409, so it can never overwrite a stored job. For a workload that should run on a schedule, use cronjob_create instead.

Argument	Type	Required	Meaning
name	string	yes	Job name — lowercase alphanumeric with hyphens, max 63 characters. Must not already exist.

It also accepts the fields of the deployment description itself, shared with the control plane’s own schema rather than restated here — see the deployment manifest reference. Two fields the manifest accepts are deliberately absent from this tool: inline secret material, because anything typed into a conversation is in the transcript for good, and the mount path, which the control plane refuses.

job_delete

Delete a Job. This DESTROYS ITS RUN HISTORY as well as the spec — every run record for the job is removed, and those records are the only artifact that the runs happened. A job managed by a CronJob cannot be deleted here; delete the CronJob instead. Requires confirm=true.

Argument	Type	Required	Meaning
name	string	yes	Job name to delete
confirm	boolean	yes	Must be true to proceed. Deleting a job also destroys every run record it has.

job_get

Get the full stored spec and current status of one Job, including its image, command, retry budget and last status message.

Argument	Type	Required	Meaning
name	string	yes	Job name

job_list

List run-to-completion Jobs with their status (pending, running, completed, failed). Use format=‘summary’ (default) for minimal output or ‘full’ for the complete stored spec. A Job whose name also appears in cronjob_list is that CronJob’s managed job and cannot be deleted directly.

Argument	Type	Required	Meaning
status_filter	one of all, pending, running, completed, failed	no	Only return jobs in this state. Default: all.
format	one of summary, standard, full	no	Response detail level: ‘summary’ (name/status/image), ‘standard’ (adds command and timings), ‘full’ (complete stored spec). Default: summary.

job_rerun

Re-run an existing Job — EXECUTES THE WORKLOAD AGAIN, now. Nothing is deleted and prior run records survive, but the work itself runs a second time, and most jobs (migrations, imports, billing runs) are not safe to repeat. Optionally re-specify the image, command or environment for this run; anything omitted is taken from the stored spec. A job that is already pending or running is refused rather than double-executed. Requires confirm=true.

Argument	Type	Required	Meaning
name	string	yes	Job name to re-run
confirm	boolean	yes	Must be true to proceed. A re-run executes the workload again.
image	string	no	Optional: run this image instead of the stored one (e.g. a newer –version for a monthly ingest). Supplying any re-spec field re-specifies the WHOLE job: the stored spec is used as the base and your fields are layered on top.
command	array	no	Optional: run this command instead of the stored one, as separate argv elements.
environment	object	no	Optional: REPLACES the stored environment map outright for this and subsequent runs — maps are not merged. Send the full desired map, not just the keys that change.

job_runs

Show the run history of a Job — what happened each time it ran, in order, oldest first. Each run records its outcome, when it started and finished, and every container attempt with its exit code (a failed attempt is retried as a new container under the same run). This is how you check the result of a job_rerun. Only the five most recent runs are kept.

Argument	Type	Required	Meaning
name	string	yes	Job name
format	one of summary, standard, full	no	Response detail level: ‘summary’ (run number, outcome, finish time), ‘standard’ (adds duration, node and the terminal reason), ‘full’ (every attempt with its container id and exit code). Default: standard.

job_update

Change a stored Job’s spec WITHOUT running it — the image, command, environment, retry budget and so on. Use this to correct a job in place; before it existed the only way was to delete and recreate, which destroyed the run history. Anything you do not send keeps its stored value. To REMOVE something (an environment variable, a network), send the full desired value with that entry left out — a field you send replaces the stored one outright, and maps are not merged. A job that is currently pending or running cannot be edited (wait for it to finish, or use job_rerun to run with a new spec), and a job owned by a CronJob must be edited through that CronJob’s template instead.

Argument	Type	Required	Meaning
name	string	yes	Job name to update

It also accepts the fields of the deployment description itself, shared with the control plane’s own schema rather than restated here — see the deployment manifest reference. Two fields the manifest accepts are deliberately absent from this tool: inline secret material, because anything typed into a conversation is in the transcript for good, and the mount path, which the control plane refuses.