list_tickets
Every input property this tool accepts, with its bounds.
Filter and page the helpdesk ticket queue.
Role required: viewer. This is the same check the HTTP route
GET /v1/tickets applies, run by the same guard object, not a second one that
could drift from it.
Source: tool definition services/runtime/src/runtime/mcp/tools.py:423-455,
handler services/runtime/src/runtime/mcp/tools.py:249-285, role check
services/runtime/src/runtime/mcp/tools.py:252-254, HTTP route
services/runtime/src/runtime/api/tickets.py:427-429.
Input
Nothing is required. Calling it with no arguments at all returns the first page of the queue.
| Property | Type | Notes |
|---|---|---|
workspace_id | string | The workspace to act in. Optional if you belong to exactly one workspace, required otherwise |
status | array of string | Filter by ticket status |
priority | array of string | Filter by priority |
source | array of string | Filter by the channel the ticket came from |
assignee | string | A user id, or me, or unassigned |
team_id | string | Filter by team |
customer_id | string | Filter by customer |
overdue | boolean | Only tickets past their due point |
q | string | Free text search |
limit | integer | Minimum 1, maximum 500, default 50 |
offset | integer | Minimum 0, default 0 |
Source: services/runtime/src/runtime/mcp/tools.py:430-451.
The accepted filter values
status, priority and source are not enumerated in this tool's schema. They
are validated by the same function the HTTP route uses, which refuses an unknown
value and names it in the error.
| Filter | Accepted values |
|---|---|
status | open, pending, on_hold, solved, closed, spam, merged, deleted |
priority | low, normal, high, urgent |
source | ai_handoff, manual, email, web_widget, phone, api, migrated, voicemail, sms, whatsapp |
Source: services/runtime/src/runtime/api/tickets.py:47-58 for the values and
services/runtime/src/runtime/api/tickets.py:512-526 for the refusal.
The bounds are real
limit and offset are re-checked inside the tool before the call reaches the
queue. A value outside the bound is refused rather than quietly replaced by the
default, and that includes limit: 0: the route says 0 is invalid, not that it
means 50.
| Bound | Value |
|---|---|
limit minimum | 1 |
limit maximum | 500 |
limit default | 50 |
offset minimum | 0 |
offset maximum | 2147483647 |
offset default | 0 |
Source: the named constants at
services/runtime/src/runtime/api/tickets.py:68-73, imported and re-applied at
services/runtime/src/runtime/mcp/tools.py:255-268.
The tool page and the route cannot disagree about these numbers, because both read the same constants rather than repeating literals.
Note one gap between the schema and the check: the schema declares a maximum for
limit but not for offset
(services/runtime/src/runtime/mcp/tools.py:446-450). The handler applies the
maximum for offset regardless, so an out of range value is refused, but a
client reading the schema will not see that upper bound advertised.
Output
The queue page as the HTTP route returns it, delivered as JSON text.
Failures
A refusal you can act on is returned as a tool error with the reason in it: an
unusable filter value, an out of range limit, an unnamed workspace when you
belong to several, revoked MCP access.
Anything unanticipated returns exactly one message, this tool call could not be completed, and the real exception with its traceback is written to the server
logs instead. That is deliberate. It is why a database error can never reach a
caller carrying the query text that produced it.
Source: services/runtime/src/runtime/mcp/tools.py:566-574.