Duvo MCP

List Cases

listCases

Read-onlyIdempotent

List cases in a queue. Supports status, date-range, free-text, and json_data field filters via query params. Set count_only=true to skip Case row selection and transformation. The normal response shape is returned with cases: [] and the matching total. For label filters, use POST /v2/queues/:queue_id/cases/search.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`field`	No	Filter on a field of a typed queue's json_data, as <path>:<operator>[:<value>] (e.g. $.invoice.amount:gte:5000). Repeat the param to require several; all must match, so two comparisons on one path express a range. Operators: equals, notEquals, in, notIn, gt, gte, lt, lte, contains, isSet, isNotSet. in/notIn take a comma-separated list; isSet/isNotSet take no value. A value is typed by shape (5000 is a number, true a boolean, 00123 a string so a leading zero survives). A path the queue's Case schema does not declare is rejected rather than ignored.
`limit`	No	Number of cases per page (1-100, default 20).
`offset`	No	Zero-based offset for pagination.
`search`	No	Full-text search across case title and data.
`status`	No	Filter by one or more status buckets (comma-separated). Values: all, pending, processing, needs_input, postponed, needs_review, resolved, canceled. `processing` covers both a case actively being worked and one waiting on its evaluation.
`sort_by`	No	Field to sort by. Default: created_at.	created_at
`priority`	No	Filter by one or more priority levels (comma-separated). Values: none, medium, high.
`queue_id`	Yes	The queue's unique identifier
`count_only`	No	Skip row selection and enrichment. The normal list response shape is returned with an empty row array and the matching total.	false
`sort_order`	No	Sort direction. Default: desc.	desc
`created_at_to`	No	Return only cases created before this ISO-8601 timestamp. The upper bound is exclusive.
`updated_at_to`	No	Return only cases updated before this ISO-8601 timestamp. The upper bound is exclusive.
`issue_severity`	No	Filter by highest failing rubric severity (comma-separated). Values: critical, medium. Severity is a facet within the issues outcome, so it returns nothing when combined with a status bucket that excludes issues. `low` is not selectable: an all-low verdict is stored as success, so no case carries it.
`created_at_from`	No	Return only cases created at or after an ISO-8601 timestamp or a lookback such as 24h or 7d.
`updated_at_from`	No	Return only cases updated at or after an ISO-8601 timestamp or a lookback such as 24h or 7d.
`awaiting_my_approval`	No	Return only cases holding an unanswered approval row assigned to you, on the case's own run. Resolved from the authenticated caller, so it names no user: an API key filters as the user who owns it, and a credential with no user behind it is rejected rather than served an empty list. Narrows within needs_input, so it returns nothing alongside a terminal status bucket.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedSep 14, 2026

addedInput schema / properties / awaiting_my_approval

Added value: +{
+  "description": "Return only cases holding an unanswered approval row assigned to you, on the case's own run. Resolved from the authenticated caller, so it names no user: an API key filters as the user who owns it, and a credential with no user behind it is rejected rather than served an empty list. Narrows within needs_input, so it returns nothing alongside a terminal status bucket.",
+  "enum": [
+    "true",
+    "false"
+  ],
+  "type": "string"
+}

Changed1 schema field changedSep 8, 2026

addedInput schema / properties / field

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    }
+  ],
+  "description": "Filter on a field of a typed queue's json_data, as <path>:<operator>[:<value>] (e.g. $.invoice.amount:gte:5000). Repeat the param to require several; all must match, so two comparisons on one path express a range. Operators: equals, notEquals, in, notIn, gt, gte, lt, lte, contains, isSet, isNotSet. in/notIn take a comma-separated list; isSet/isNotSet take no value. A value is typed by shape (5000 is a number, true a boolean, 00123 a string so a leading zero survives). A path the queue's Case schema does not declare is rejected rather than ignored."
+}

Changed1 schema field changedAug 19, 2026

changedInput schema / properties / status / description

Previous value: -"Filter by one or more status buckets (comma-separated). Values: all, pending, processing, needs_input, postponed, needs_review, resolved, canceled."New value: +"Filter by one or more status buckets (comma-separated). Values: all, pending, processing, needs_input, postponed, needs_review, resolved, canceled. `processing` covers both a case actively being worked and one waiting on its evaluation."

Changed1 schema field changedAug 18, 2026

addedInput schema / properties / issue_severity

Added value: +{
+  "description": "Filter by highest failing rubric severity (comma-separated). Values: critical, medium. Severity is a facet within the issues outcome, so it returns nothing when combined with a status bucket that excludes issues. `low` is not selectable: an all-low verdict is stored as success, so no case carries it.",
+  "type": "string"
+}

First observedAug 17, 2026

TDQS

A3.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: count_only skips row selection and transformation, and the response shape still returns with an empty cases array plus the matching total.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences with the core purpose front-loaded and the count_only behavior immediately after. Slight overlap with the schema's own wording, but no wasted sentences.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema present, the description carries the return-shape burden and does so by describing the count_only response (empty cases array plus total). Combined with the fully documented 16-param schema, an agent has enough to invoke it correctly, though general pagination/return guidance is thin.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the schema itself is unusually detailed, so the baseline is 3. The description only summarizes the filter families generically (status, date-range, free-text, json_data) without adding operator or format detail beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("List cases in a queue") plus the supported filter families. It never names a sibling like searchCases or exportCases directly, though it names the search endpoint as an alternative for label filters, which helps an agent distinguish the two paths.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives one concrete routing rule (use POST /v2/queues/:queue_id/cases/search for label filters) and explains the count_only switch, but says nothing about when to prefer listCases over searchCases or exportCases in general, or about pagination strategy.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Duvo MCP tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?