Provides tools for inspecting and managing RQ (Redis Queue) jobs, queues, and workers on a Redis instance, including enqueueing, requeueing, canceling jobs, running health checks, and performing admin operations like deleting jobs or suspending workers.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@rq-mcp show me the failed jobs and summarize the exceptions"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP (Model Context Protocol) server for RQ (Redis Queue), letting AI agents inspect, debug, and operate RQ queues, jobs, and workers.
Phase 1 (read-only), Phase 2 (write: enqueue/requeue/cancel), and Phase 3 (admin: delete/purge/worker shutdown) are all complete — see the "Modes" section below and "Available tools" for the full surface.
Related MCP server: redis-mcp-server
Python 3.14+
A running Redis instance (a docker-compose.yml is provided for local dev)
Docker — only needed if you use the
provided docker-compose.yml instead of your own Redis
uv syncAll configuration is via environment variables.
Variable | Default | Purpose |
|
| Redis connection string |
|
|
|
|
|
|
|
|
|
|
|
|
| unset | Path to a TOML file listing functions |
export REDIS_URL="redis://localhost:6379/0"RQ_MCP_MODE gates which tools get registered: readonly (default)
exposes only inspection tools (12); write adds enqueue/requeue/cancel
tools (6 more, 18 total); admin adds delete/purge/worker-shutdown tools
(6 more, 24 total). Modes are cumulative — admin gets write and
readonly tools too.
admin mode grants genuinely destructive capabilities — permanently
deleting jobs, wiping entire status registries, emptying queues, shutting
down or globally suspending workers. Don't set RQ_MCP_MODE=admin against
a Redis instance you don't want an AI agent able to disrupt.
suspend_workers is global, not scoped to a queue or a single
worker: it stops every RQ worker sharing that Redis connection from
picking up new jobs, regardless of which queue(s) they listen to. This
is RQ's own suspend mechanism (rq.suspension), not something rq-mcp
narrows down. resume_workers undoes it (also globally); an optional
ttl on suspend_workers can auto-expire the suspension.
This spins up Redis, puts demo data on a couple of queues, and lets you call the MCP tools interactively through the MCP Inspector — no AI client required.
# 1. Start Redis
docker compose up -d
# 2. Seed demo data across every job/queue/worker state
uv run python scripts/seed_demo_data.py
# 3. Launch the server with the MCP Inspector (opens a browser UI)
uv run mcp dev src/rq_mcp/server.pyscripts/seed_demo_data.py (see "Local dev / example data" below) seeds
queued, scheduled, deferred, finished, and failed jobs (two different
exception types, so summarize_failures has something to group), plus a
fake stale worker entry so health_check reports a finding out of the box.
For a lighter touch — just a couple of queued jobs — use
examples/seed_queues.py instead.
In the Inspector UI, connect and use "List Tools" to see the tools for
your current RQ_MCP_MODE (see "Available tools" below), and "List
Prompts" for the 5 guided workflows. mcp dev requires the cli extra,
which is already included as a dev dependency.
list_jobs/summarize_failures/list_scheduled_jobs are how you discover
job IDs to pass to get_job/get_job_result — none of the seed scripts
print them directly.
Optionally, run a real worker in another terminal so jobs keep getting
processed live, and so you have a live worker to inspect with
list_workers/get_worker (this is on top of seed_demo_data.py's
built-in one-shot processing — a live worker keeps running afterward):
uv run python examples/worker.pySee examples/ and scripts/ for the job
definitions and seed scripts.
When you're done:
docker compose down -vOutside of the Inspector, the server communicates over stdio, so it's normally launched by an MCP client (e.g. Claude Desktop, Claude Code) rather than run standalone. To start it directly:
uv run rq-mcp
# or
uv run python -m rq_mcpreadonly mode and above)All 12 of these are read-only (readOnlyHint: true).
System
get_rq_info — Redis connection status, Redis/RQ versions, discovered
queue names, and worker count.
redis_info — selected Redis INFO fields (used_memory, maxmemory,
maxmemory_policy, evicted_keys, connected_clients, per-database key
counts), by section (defaults to memory/clients/stats/keyspace).
Queues
list_queues — per queue: job counts by status (queued, started,
finished, failed, deferred, scheduled, canceled) and worker count.
get_queue — the same per-queue detail plus the oldest queued job's age
in seconds and default_timeout.
Jobs
get_job — full details for a single job by ID (status, origin queue,
function name, redacted/truncated args/kwargs/meta, timeout, ttl,
dependency IDs, worker name, lifecycle timestamps), or null if the job
doesn't exist.
get_job_result — a job's result or exception info, truncated to
max_bytes (default 2000), or null if the job doesn't exist.
list_jobs — jobs in a queue filtered by status, paginated
(offset/limit, max 100 per page), with a total count.
summarize_failures — a queue's failed jobs grouped by function name +
exception type: count, an example job ID, first/last failure time.
list_scheduled_jobs — a queue's scheduled jobs: ID, function name,
scheduled time, paginated.
Workers
list_workers — every registered worker (optionally filtered by queue):
name, state, queues, current job ID, heartbeat + age, job counters.
get_worker — full details for a single worker by name (state, hostname,
IP, PID, queues, current job ID, timestamps, job counters, total working
time), or null if it isn't currently registered.
Health
health_check — runs six diagnostics across queues/workers/Redis and
returns {"ok": bool, "findings": [...]}. Finding codes:
QUEUE_NO_WORKERS, WORKER_STALE_HEARTBEAT, ORPHANED_STARTED_JOB,
OLDEST_JOB_TOO_OLD, REDIS_EVICTION_RISK, HIGH_FAILURE_COUNT.
write mode and above)Mutate job state, but nothing here deletes data or touches workers.
list_task_functions — the enqueue whitelist loaded from
RQ_MCP_TASK_WHITELIST (name, description, args per entry).
enqueue_task — enqueue a whitelisted function by dotted name
(func_name must be in list_task_functions's output — nothing else
can be enqueued), immediately or scheduled via at/in_seconds.
requeue_job — requeue a single failed job.
requeue_failed — bulk-requeue a queue's failed jobs, optionally
filtered by function name/exception type; dry_run=True by default.
cancel_job — cancel a queued/scheduled/deferred job.
stop_running_job — send a stop signal to a currently-executing job.
admin mode only)Destructive. delete_job/clear_registry/empty_queue/
shutdown_worker/suspend_workers all require confirm=True to
actually act (or dry_run=True to preview the affected count first,
which needs no confirmation). resume_workers needs neither.
delete_job — permanently delete a single job.
clear_registry — permanently delete every job in one queue's status
registry (started/finished/failed/deferred/scheduled/canceled).
empty_queue — permanently delete every queued job in a queue.
shutdown_worker — send a shutdown command to one named worker.
suspend_workers — global: stop every worker on this Redis from
picking up new jobs (see the warning above).
resume_workers — undo suspend_workers (also global); no
confirmation needed.
Five guided read-only diagnostic workflows, each naming which tools above to call, in order, and what to conclude from the results:
diagnose_queue(queue_name)
triage_failed_jobs(queue_name, limit)
why_is_job_stuck(job_id)
capacity_check()
post_deploy_check()
uv run pytestTwo layers of tests, neither requiring a running Redis instance:
tests/test_rq_service.py, tests/test_config.py, tests/test_helpers.py,
tests/test_audit.py, tests/test_prompts.py — mock the Redis
connection (unittest.mock); fast, cover most branches directly.
tests/test_integration.py — runs real RQService methods against a
real redis/rq API surface backed by an in-memory
fakeredis instance (using
RQ's non-forking SimpleWorker so job execution stays visible to the
test process). Covers scenarios that are awkward to fully exercise with
mocks: an orphaned started-job registry entry (real composite-key
format), mixed-exception grouping, and pagination boundaries.
uv run ruff check .
uv run ruff format --check .Simple layered src layout, no unnecessary abstractions. See
ARCHITECTURE.md for the full layer breakdown, request
lifecycle, and shared helpers (pagination, redaction, truncation).
docker-compose.yml — a local Redis 7 instance for development, not used
in production or in tests.
examples/ — minimal scripts (tasks.py, seed_queues.py,
worker.py) for a quick two-queue smoke test. Not part of the
installable package.
scripts/seed_demo_data.py (+ seed_tasks.py) — a richer seed covering
every job status, two distinct exception types, and a hand-crafted stale
worker entry, so every Phase 1 tool (including health_check's findings
and summarize_failures's grouping) has something real to show. Not
part of the installable package.
A few things discovered while building this that aren't obvious from RQ's own docs:
Queue's default_timeout isn't persisted to Redis. It's a
Python-side constructor default (180s) that only exists in the process
that created the Queue object — get_queue's default_timeout field
reflects this server's default, not necessarily what any given
producer used (each job's own .timeout, exposed via get_job, is the
real source of truth per job).
worker.queue_names() is a method, not a property in rq==2.12.0 —
easy to get wrong since many other worker fields are plain attributes.
worker.get_current_job_id() does a live Redis round trip every
call; it isn't populated by Worker.all()'s bulk refresh().
RQ doesn't expose a structured exception class, only the raw
traceback text (Result.exc_string) — summarize_failures parses the
traceback's last line by convention (ExceptionType: message).
StartedJobRegistry.add() raises NotImplementedError in this RQ
version (an unimplemented base-class stub); entries are written directly
via ZADD with a "{job_id}:{execution_id}" composite key internally by
the worker. Relevant if you ever need to hand-craft a started-registry
entry (as scripts/seed_demo_data.py's tests do).
fakeredis doesn't implement the INFO command — get_info() and
redis_info() degrade gracefully against it (their existing
RedisError handling), but don't expect real memory/stats data from
integration tests.
A non-forking SimpleWorker burst-processing several jobs in one
long-lived process intermittently failed to re-resolve later jobs'
function imports in this environment (Python 3.14 / rq 2.12.0) when
the task module was only importable via a bare sys.path[0]-relative
script directory (not a proper package). Not fully root-caused; worked
around by using the regular forking Worker wherever multiple real
jobs need to run outside of fakeredis-backed tests (see
scripts/seed_demo_data.py).
Return full details for a single RQ job by ID, or null if it does not exist.
Includes status, origin queue, function name, redacted/truncated
args/kwargs/meta, timeout, ttl, dependency IDs, worker name, and
lifecycle timestamps. Does not include the job's result or
exception info -- use get_job_result for that.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds meaningful behavioral details beyond annotations: the null return for missing jobs, redaction/truncation of args/kwargs/meta, and the explicit exclusion of result/exception data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the primary behavior, and uses a brief field list followed by an explicit exclusion. Every sentence earns its place; there is no repetition of schema or annotation data.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read-only tool with a rich output schema and strong annotations, the description is complete. It tells the agent what is returned, what is not returned, the null case, and the correct alternative tool. Nothing needed for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter, job_id, with 0% description coverage, so the description carries the burden. It contributes 'by ID' and identifies the resource as an RQ job, but it does not explain the expected format or source of the job ID. The parameter name is self-explanatory, but the description could have added more concrete guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Return full details for a single RQ job by ID, or null if it does not exist.' It names the included fields and explicitly differentiates from get_job_result by stating what this tool does not return. An agent can select this tool confidently among the siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: use this for full single-job metadata, and use get_job_result when the job's result or exception info is needed. This explicit when/not/alternative guidance leaves no ambiguity about routing to the correct sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return a job's result/exc_info, or null if the job does not exist.
Truncated to max_bytes, with a truncated flag when that
happened.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | ||
| max_bytes | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, and the description adds valuable behavioral details: truncation to max_bytes, the truncated flag, and null on missing job. This goes beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with the primary action front-loaded and a precise secondary note on truncation. No redundancy or extraneous content; every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (2 params), has an output schema, and annotations cover safety. The description covers the null case, truncation, and the flag, which is all an agent needs to call it correctly. Nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains max_bytes through the truncation behavior, but job_id is only implicitly understood from context. While not fully exhaustive, it provides sufficient semantics for the key parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: returning a job's result/exc_info, and specifies the null case for nonexistent jobs. This distinguishes it from sibling get_job, which likely returns broader job metadata, by focusing on the result payload specifically.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (to fetch a job's result) but does not explicitly contrast it with siblings like get_job or list_jobs. An agent is left to infer the selection criteria without explicit 'use this instead of X' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return detailed status for a single queue by name.
Includes the same per-status counts as list_queues, the age in
seconds of the oldest still-queued job (null if empty), and
default_timeout in seconds (reflects this server's own default,
since RQ does not persist a per-queue default_timeout to Redis).
An unknown queue name is not an error -- RQ queues are
lazy/virtual, so it returns the same shape with all counts at 0.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses meaningful behaviors: the age of the oldest queued job and null when empty, the default_timeout nuance regarding RQ persistence, and the important edge case that unknown queue names are valid and return zero counts. This is substantial added context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and the subsequent sentences each add non-redundant, useful details. Referencing list_queues instead of restating count fields keeps it efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for a simple single-queue status tool: it covers the fields returned, an important edge case, and a subtle behavior about default_timeout. The presence of an output schema means return-value details do not need to be duplicated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description must carry the meaning of the single 'name' parameter. It does so by explaining that the parameter identifies the queue and that unknown names are not errors. It does not provide format constraints, but none are needed beyond string type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb ('Return') and resource ('detailed status for a single queue by name'), making the tool's scope immediately clear. It also references list_queues to clarify the relationship and differentiates this tool as the single-queue counterpart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies the use case: query one queue's status by name, and it references list_queues for the multi-queue context. It does not explicitly state when not to use this tool or name alternative decision rules, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return basic information about the Redis/RQ environment.
Includes Redis connection status, Redis/RQ versions, discovered queue names, and the number of active workers.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered elsewhere. The description adds useful context about what information is surfaced, but no additional behavioral traits such as error behavior, cost, or network sensitivity. It does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two tightly written sentences: the first states the purpose, the second enumerates the return contents. There is no filler, and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-parameter read-only tool with an output schema and strong annotations, the description is largely complete. It explains what the tool returns and implies an environment-overview use case, though it could have briefly contrasted itself with redis_info or list_queues.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so parameter semantics are automatically satisfied and the description does not need to compensate. The 100% schema description coverage and empty properties schema make parameter confusion impossible.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a clear verb ('Return') and specifies the resource ('Redis/RQ environment') and the exact contents: connection status, versions, queue names, and worker count. It is clear enough to distinguish from the more specialized siblings, though it does not explicitly differentiate itself like the get_calls example.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as redis_info, list_queues, or list_workers. The description states what it returns but provides no exclusions, conditions, or explicit routing to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return full details for a single worker by name, or null if not currently registered.
Includes state, hostname, IP address, PID, queue names, current job ID (if any), birth/last-heartbeat timestamps (plus heartbeat age in seconds), job counters, and total working time in seconds.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only and idempotent, so the description adds the null behavior and enumerates the fields returned, giving concrete behavioral detail beyond the annotations. It does not contradict any annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise and well-structured: purpose is front-loaded, followed by a clear enumeration of returned fields. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple single-parameter input and the presence of an output schema (not shown), the description lists the return fields, so an agent knows what to expect. The null case is covered, and no gaps are apparent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no description for the 'name' parameter, but the tool description clarifies it refers to a worker's name. No additional detail on format or constraints is given, but for a simple string this is adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns full details for a single worker by name, with a specific null return for unregistered workers. It distinguishes from siblings like list_workers (which lists all) by focusing on a single-worker lookup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context that it retrieves a single worker by name, implying use when a specific worker name is known. It does not explicitly mention alternatives or when not to use, but the purpose is unambiguous and self-evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run read-only diagnostics across queues, workers, and Redis itself.
Returns {"ok": bool, "findings": [...]}; findings is empty and
ok is true when nothing is wrong. Each finding has a severity,
a stable code (QUEUE_NO_WORKERS, WORKER_STALE_HEARTBEAT,
ORPHANED_STARTED_JOB, OLDEST_JOB_TOO_OLD, REDIS_EVICTION_RISK,
HIGH_FAILURE_COUNT), a human-readable message, and structured
details.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool read-only, idempotent, and non-destructive, and the description aligns perfectly by stating 'read-only diagnostics.' The description adds useful behavioral context: the result is an `ok` boolean plus a list of structured findings with stable error codes, which helps an agent interpret the outcome of the call.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: one sentence states the action, and the rest specifies the return contract with useful constants. The list of stable codes is dense but relevant, and nothing is redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a diagnostic tool with no parameters and a fully described return shape, the description covers what an agent needs. The mention of specific finding codes and their semantic fields makes the tool's behavior predictable even without probing the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and an empty input schema, so there is nothing to document. Per the baseline for zero-param tools, the description is not required to add parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Run read-only diagnostics across queues, workers, and Redis itself.' This clearly distinguishes it from siblings that target single components, and the preview of the output shape removes ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The scope statement implies this is the aggregate health check while siblings like get_rq_info, redis_info, and list_queues drill into specific components. However, it never explicitly states 'use this when you need an overall status' or names alternatives, so the guidance is implicit rather than direct.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List jobs in a queue filtered by status.
status must be one of: queued, started, finished, failed,
deferred, scheduled, canceled. Returns up to limit (max 100) job
summaries (id, function name, description, status, enqueued_at,
started_at, ended_at) starting at offset, plus the total number
of jobs at that status in the queue.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No | ||
| status | Yes | ||
| queue_name | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, non-destructive behavior, so the bar for the description is lower. The description goes beyond the annotations by disclosing a hard operational constraint absent from the schema — 'max 100' on limit — plus the exact status vocabulary (an enumerated contract since the schema defines no enum) and the response shape. It does not disclose error behavior, but for a read-only listing tool that gap is minor.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight paragraphs: the purpose is front-loaded in the first sentence, and everything after earns its place by documenting constraints the schema lacks (status values, limit cap, response fields). No filler, no repetition of annotation or schema content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple filtered-list operation, the description is nearly complete: the output schema covers the return shape, annotations cover safety, and the description covers the status contract and pagination bounds. The only residuals are queue_name semantics and absence of error/empty-result behavior, which are minor for a read-only enumeration tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the full burden — and it mostly delivers. status is fully enumerated, limit has an explicit max of 100, and offset is explained as the pagination start. queue_name is only weakly indicated ('in a queue'), but the other three parameters get meaning the schema does not provide, which properly compensates for the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening line 'List jobs in a queue filtered by status' names a specific verb, resource, and scope. It is clearly distinguishable from siblings: get_job and get_job_result target single jobs, list_scheduled_jobs is a narrower status filter, and list_queues/list_workers target different resource types. No ambiguity about what this tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the purpose — an agent can infer this enumerates jobs at a given status, including scheduled ones, which overlaps with list_scheduled_jobs. However, there is no explicit when-to-use vs. when-not-to-use guidance, and no siblings are named. A quick routing note ('for a single job use get_job; for scheduled-only use list_scheduled_jobs') would remove the ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all discovered RQ queues.
Returns, per queue: job counts by status (queued, started, finished, failed, deferred, scheduled, canceled) and the number of workers currently listening to it.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds useful scope detail ('discovered' queues) and explicitly enumerates the return fields, which informs the agent about what to expect beyond the bare annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler: the first states the core action and scope, the second details the return payload. Every sentence earns its place and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only list tool with full annotations and an output schema, the description covers scope and return contents sufficiently. There are no missing prerequisites, error modes, or side-effect disclosures that the agent would need here.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the schema provides complete coverage. The description correctly adds no parameter information, which is appropriate and earns the established baseline of 4 for parameterless tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource pair ('List all discovered RQ queues') and clearly states what is returned (job counts by status, worker count). The scope 'all discovered' distinguishes it from per-queue tools like get_queue and jobs-focused tools like list_jobs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (to get an overview of all queues and their workload) but does not explicitly mention alternatives or conditions for when not to use it. No direct comparison with siblings like get_queue or list_workers is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List scheduled jobs in a queue: id, function name, and scheduled time.
Returns up to limit (max 100) entries starting at offset,
plus the total number of scheduled jobs in the queue.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No | ||
| queue_name | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal readOnly, idempotent, and non-destructive behavior. The description adds meaningful pagination semantics: up to `limit` (max 100) entries starting at `offset`, plus a total count. This goes beyond the structured fields and helps the agent understand response behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two dense sentences with no filler. The purpose is front-loaded, and the pagination details are presented in a compact, readable way. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list operation with output schema present, the description covers the key behaviors: returned fields, pagination, and total count. It does not mention edge cases like nonexistent queues, but given the low complexity and supportive annotations, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains `limit` and `offset` behavior clearly, including the maximum limit, and the phrase 'in a queue' implies that `queue_name` selects the target queue. It does not, however, explicitly describe the queue_name parameter's format or required status, leaving a small gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List') and resource ('scheduled jobs in a queue') and enumerates the returned fields (id, function name, scheduled time). This clearly distinguishes it from sibling tools like list_jobs or get_job by scoping to scheduled entries in a queue.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is implied by the description and the required queue_name parameter, but there is no explicit guidance on when to choose this tool over siblings such as list_jobs or get_queue. No exclusions or alternative routing is provided, so the agent must infer usage from context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List currently registered RQ workers, optionally filtered by queue.
Returns, per worker: name, state (idle/busy/started/suspended),
the queue names it listens to, the ID of the job it's currently
processing (if any), last heartbeat and its age in seconds, and
its successful/failed job counters. If queue is given, only
workers listening to that queue are returned.
| Name | Required | Description | Default |
|---|---|---|---|
| queue | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by detailing the return structure (state, job ID, heartbeat, counters) and the optional filter behavior, providing more than the annotations alone. It does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but organized: front-loads the primary action, enumerates return fields in a list, and then clarifies parameter behavior. Every sentence earns its place, and there is no redundant phrasing or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a single optional parameter and an output schema already present, the description fully covers what the tool does, what it returns, and how the parameter affects results. Nothing an agent needs to call it correctly is missing, and the prose return-field enumeration complements the output schema rather than repeating it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for parameter meaning. It does: 'If `queue` is given, only workers listening to that queue are returned' fully explains the effect of the single optional parameter. No further syntax is needed for a string parameter, and the default null is implicit in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists currently registered RQ workers with an optional queue filter, and enumerates the exact per-worker fields returned (name, state, queues, current job ID, heartbeat, counters). This is a specific verb+resource that is plainly distinct from sibling tools like get_worker (singular worker) or list_jobs (jobs).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the optional 'queue' parameter's effect (only workers listening to that queue are returned) but does not explicitly mention when to use this tool versus alternatives such as get_worker or list_queues. The purpose is clear enough that an agent can infer usage, but it lacks explicit exclusionary guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return selected Redis INFO fields.
Defaults to memory, clients, stats, and keyspace sections:
used_memory, maxmemory, maxmemory_policy, evicted_keys,
connected_clients, and per-database key counts. Unrecognized
section names are ignored and listed in ignored_sections
rather than raising an error.
| Name | Required | Description | Default |
|---|---|---|---|
| sections | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint, idempotentHint, and destructiveHint as safe. The description adds meaningful behavioral detail beyond that: unrecognized section names are silently ignored and listed in `ignored_sections` instead of raising an error. This is exactly the kind of non-obvious behavior an agent needs to know before calling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences carry the essential payload: what the tool does, what the defaults are, and how edge-case inputs are handled. No filler, no repetition of schema fields, and the most important behavior is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-optional-parameter, read-only tool with an output schema already defined, the description covers everything needed to call it correctly: purpose, defaults, and non-erroring edge-case behavior. The lack of an explicit list of valid sections is mitigated by the tool's tolerant handling of unrecognized names.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only the type and default for `sections` (0% coverage), so the description must compensate. It explains the default sections and the handling of unrecognized names, which is useful, but it never enumerates valid section name values or shows an example of the expected array format. This is a partial compensation, not a full one.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Return selected Redis INFO fields.' It clearly lists the default sections and fields, and the tool is immediately distinguishable from the RQ-focused sibling tools. Even without opening the schema, an agent knows what this tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context by explaining the default sections and how the sections parameter behaves. It doesn't explicitly name alternative tools or say when not to use it, but none of the siblings obviously overlap with Redis INFO inspection, so this is a minor omission rather than a confusion risk.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Group a queue's failed jobs by function name + exception type.
Scans up to limit failed jobs (default 200) and returns one
entry per (function, exception type) group: count, an example
job ID, and first/last failure timestamps.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| queue_name | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context beyond that by disclosing that it scans up to `limit` failed jobs (default 200) and aggregates results per group. This informs the agent about potential partial coverage and the exact return shape.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler. The primary purpose is front-loaded in the first sentence, and the second sentence efficiently details the scanning behavior and output structure. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only summary tool with only two simple parameters and an available output schema, the description covers all essential operational details: grouping keys, limit behavior, and the fields in each group. There are no significant gaps that would prevent correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description compensates by explaining `limit` as the scan cap and mentioning the default 200. It also clarifies that `queue_name` identifies the queue being summarized. Both parameters receive practical meaning that the raw schema lacks.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Group') and resource ('a queue's failed jobs') along with the grouping keys (function name + exception type) and the output fields. This clearly distinguishes it from sibling tools like list_jobs or get_job, which operate on individual jobs or queues.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by explaining the aggregation behavior, but it does not explicitly state when to prefer this tool over alternatives such as list_jobs. No exclusions or when-not-to-use conditions are provided, so guidance is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0get_jobget_job_resultget_queueget_rq_infoget_workerhealth_checklist_jobslist_queueslist_scheduled_jobslist_workersredis_infosummarize_failuresScored across 12 tools
Each tool targets a distinct RQ resource or view: environment info, Redis internals, queues, jobs, results, workers, failures, and health. The only close pair is list_jobs with status=scheduled and list_scheduled_jobs, but their return shapes and descriptions make the intended use clear.
The naming is mostly predictable with get_ for single entities and list_ for collections, all in snake_case. summarize_failures and health_check deviate slightly from the get_/list_ pattern but remain readable and consistent in style.
Twelve tools is well-scoped for an RQ monitoring and inspection server. Each tool covers a meaningful part of the domain without unnecessary redundancy or bloat.
The tool surface covers the major RQ monitoring areas: environment, Redis health, queues, jobs by status, individual job details and results, scheduled jobs, workers, failure aggregation, and health diagnostics. For a read-only monitoring server, there are no obvious dead ends or missing core operations.
Durable background job execution, async task scheduling, and state persistence for AI agents.
Reliable async execution for agent tool calls: schema gating, retries, idempotency, audit trail.
Give your AI agents the tools to build, manage, and run automation workflows.
Connect, monitor, and control AI agents — tasks, approvals, schedules, and governance.
