Tools reference
Once connected, an agent can call the tools below. Each tool enforces the agent's permissions on the queue's team and records the call in the audit log. Tools are annotated so MCP clients can visually distinguish read-only from destructive actions.
MCP clients discover each tool's full input schema automatically. The tables below summarize the arguments. Every tool that acts on a queue takes a queueId, which you get from list_queues.
Read tools
Queue-scoped read tools require the View queues permission (can_view_queues) on the queue's team. get_permissions and list_queues take no queue and can always be called. They only return what the agent already has access to: list_queues omits queues on teams where the agent lacks View queues.
| Tool | Arguments | What it does |
|---|---|---|
get_permissions | none | List the teams the agent belongs to, its role in each, and the actions it may perform |
list_queues | none | List every queue the agent can access, with the ids used by other tools |
get_job_counts | queueId | Job counts per state (waiting, active, completed, failed, delayed, paused) |
get_queue_metrics | queueId | Throughput metrics (completed/failed over time) plus current counts |
list_jobs | queueId, state, limit?, offset?, nameFilter?, reasonFilter? | List jobs in a state (waiting, active, completed, failed, delayed, prioritized). limit defaults to 10 (max 50). Returns a nextOffset for paging, or null on the last page |
list_failed_jobs | queueId, limit? | The most recent failed jobs, including each failure reason. limit defaults to 10 (max 50) |
get_job | queueId, jobId | Full details of a single job (data, options, progress, result or failure reason) |
get_job_logs | queueId, jobId, limit? | The log lines a worker recorded for a job. limit defaults to 50 (max 100) |
get_flow | queueId, jobId | A parent job's flow: its details plus processed/unprocessed children |
list_job_schedulers | queueId, limit? | The repeatable / cron job definitions for a queue. limit defaults to 20 (max 50) |
Filtering
nameFilter and reasonFilter are case-insensitive "contains" matches, applied to the page that was fetched. A filtered page can therefore hold fewer than limit jobs. Keep following nextOffset to scan the whole state.
Write tools
Write tools require the matching action permission and are not available to read-only tokens. Tools marked destructive remove data. Several support a dryRun argument that previews the impact without making any change.
| Tool | Arguments | Permission required | Notes |
|---|---|---|---|
retry_job | queueId, jobId | Retry jobs | Retry one failed job |
retry_jobs | queueId, jobIds | Retry jobs | Retry a specific set of jobs (1–100 ids) |
promote_job | queueId, jobId | Promote jobs | Promote one delayed job so it runs now |
promote_jobs | queueId, jobIds | Promote jobs | Promote a specific set of delayed jobs (1–100 ids) |
remove_job | queueId, jobId | Delete jobs | Destructive. Remove one job |
remove_jobs | queueId, jobIds, dryRun? | Delete jobs | Destructive. Remove a set of jobs (1–100 ids) |
add_job | queueId, name, data?, opts? | Add jobs | Enqueue a new job. opts accepts delay (ms), priority (lower runs first) and attempts |
retry_all_failed | queueId | Retry all | Retry every failed job in a queue |
pause_queue | queueId | Pause queues | Pause processing |
resume_queue | queueId | Pause queues | Resume processing |
clean_queue | queueId, status, dryRun? | Clean queues | Destructive. Bulk-remove completed or failed jobs. Jobs that finished in the last 10 seconds are kept |
remove_job_scheduler | queueId, schedulerId | Delete jobs | Destructive. Remove a repeatable/scheduled job definition, using the id from list_job_schedulers |
obliterate_queue | queueId, force?, dryRun? | Delete queues | Destructive. Delete a queue and all its jobs. Refuses while jobs are active unless force is true |
The bulk tools (retry_jobs, promote_jobs, remove_jobs) never abort halfway. They return which ids succeeded, which were notFound, and any per-id errors.
Selective retry
Prefer retry_jobs with the specific ids that are safe to retry (for example, only the transient failures) over retry_all_failed. It's a single, auditable action that leaves genuinely broken jobs untouched for a human to fix.
Dry run first
For destructive bulk actions, call the tool with "dryRun": true first. It returns a preview of exactly what would be removed, and makes no changes, so the agent (and you) can confirm before committing.
Example: an agent triaging failures
A typical investigation-then-fix sequence an agent might run:
list_queues → find the welcome-emails queue
get_job_counts(queueId) → 5 failed
list_jobs(queueId, "failed") → 3 transient SMTP errors, 2 invalid addresses
retry_jobs(queueId, [ids…]) → retry only the 3 safe ones
get_job_counts(queueId) → 3 completed, 2 still failed (left for a human)