Skip to main content
Glama

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.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "queue_id": "<queue_id>"
    },
    "name": "listCases"
  }
}

Input Schema

NameRequiredDescriptionDefault
fieldNoFilter 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.
limitNoNumber of cases per page (1-100, default 20).
offsetNoZero-based offset for pagination.
searchNoFull-text search across case title and data.
statusNoFilter 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_byNoField to sort by. Default: created_at.created_at
priorityNoFilter by one or more priority levels (comma-separated). Values: none, medium, high.
queue_idYesThe queue's unique identifier
count_onlyNoSkip row selection and enrichment. The normal list response shape is returned with an empty row array and the matching total.false
sort_orderNoSort direction. Default: desc.desc
created_at_toNoReturn only cases created before this ISO-8601 timestamp. The upper bound is exclusive.
updated_at_toNoReturn only cases updated before this ISO-8601 timestamp. The upper bound is exclusive.
issue_severityNoFilter 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_fromNoReturn only cases created at or after an ISO-8601 timestamp or a lookback such as 24h or 7d.
updated_at_fromNoReturn only cases updated at or after an ISO-8601 timestamp or a lookback such as 24h or 7d.
include_blockersNoAlso return `blocker` on each case: for a case waiting to start, why the dispatcher cannot start it now, or null when nothing blocks it. Off by default, because it adds database reads; when off, `blocker` is left out.
awaiting_my_approvalNoReturn 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.

  1. Changed1 schema field changed
    • addedInput schema / properties / include_blockers
      Added value: +{
      +  "description": "Also return `blocker` on each case: for a case waiting to start, why the dispatcher cannot start it now, or null when nothing blocks it. Off by default, because it adds database reads; when off, `blocker` is left out.",
      +  "enum": [
      +    "true",
      +    "false"
      +  ],
      +  "type": "string"
      +}
  2. Changed1 schema field changed
    • 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"
      +}
  3. Changed1 schema field changed
    • 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."
      +}
  4. Changed1 schema field changed
    • 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."
  5. Changed1 schema field changed
    • 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"
      +}
  6. First observed

TDQS

A3.7/5.0
Behavior4/5

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

Annotations already cover the read-only, idempotent, non-destructive profile, and the description adds real behavior on top: count_only skips row selection and transformation, still returns the normal envelope with an empty array plus the matching total, and label filtering is unsupported here. It doesn't mention pagination interaction or how deep the returned rows are, which keeps it off a 5.

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?

Four short sentences, front-loaded with the core purpose and then the exception cases. The count_only sentence and the 'normal response shape ... cases: []' sentence partially overlap with the count_only schema description, which is mild redundancy rather than bloat.

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?

For a 17-parameter read tool with no output schema, the description covers the purpose, the special count_only mode, the response envelope behavior, and one exclusion. A mention of pagination limits or expected row shape would make it fully self-sufficient, but nothing critical is missing.

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% across all 17 parameters, including detailed prose for `field`, `status`, `issue_severity`, and `awaiting_my_approval`, so the schema already carries the semantics. The description only restates the filter categories and the count_only behavior, adding little beyond what is structured.

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?

The description opens with a specific verb and resource ('List cases in a queue') and names the filter families it supports, so an agent knows immediately what it does. It falls short of a 5 because the alternative is identified by raw HTTP path ('POST /v2/queues/:queue_id/cases/search') rather than by the sibling tool name (searchCases), which is what the agent actually has to choose between.

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?

There is one useful routing rule — label filters must go to the search endpoint instead — and a clear note on when to use count_only. But the description never says when to prefer searchCases or exportCases over this tool for ordinary listing, so the choice among the closely related siblings is only implied.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources