swsd-mcp

swsd_list_incidents

Read-onlyIdempotent

List and filter SWSD incidents by state, priority, category, assignee, requester, date, or site, with paginated summaries to quickly locate tickets needing attention.

Instructions

List SWSD incidents with structured filters and pagination. Returns compact summaries (id, name, state, priority, assignee_email, requester_email, category, updated_at) — call swsd_get_incident for the full detail of any one row. Filters use SWSD repeated-key array semantics (multiple values within a filter are OR-ed). NOTE: assignee_email and requester_email are applied CLIENT-SIDE because SWSD /incidents.json silently ignores them server-side (verified 2026-05-08 against the live API). Other filters (state, category, dates, sites, departments, assigned_to_group, query) DO narrow server-side and are passed through.

Input Schema

TableJSON Schema

Name	Required	Description
`page`	No	Page number (1-indexed).
`query`	No	Free-text search across incident title and description. Same async-indexing caveat as solution search — just-created tickets may not appear for a few minutes.
`sites`	No	Filter to incidents at any of these site names (use swsd_list_sites to discover).
`states`	No	Filter to incidents matching ANY of these states (e.g. ["New", "Assigned"]).
`sort_by`	No	Sort key. Default is SWSD-side (typically updated_at desc).
`per_page`	No	Results per page (1-100). SWSD caps at 100.
`categories`	No	Filter to incidents matching ANY of these category names.
`created_to`	No	Filter to incidents created on or before this ISO date or datetime.
`priorities`	No	Filter to incidents matching ANY of these priorities (e.g. ["High", "Medium"]).
`sort_order`	No	Sort direction. Use uppercase per SWSD convention.
`updated_to`	No	Filter to incidents updated on or before this ISO date or datetime. Pair with updated_from for an explicit range.
`departments`	No	Filter to incidents in any of these department names.
`created_from`	No	Filter to incidents created on or after this ISO date or datetime (YYYY-MM-DD or RFC 3339).
`state_is_not`	No	Negative state filter: exclude incidents in any of these states (e.g. ["Resolved", "Closed"] to see only open work).
`updated_from`	No	Filter to incidents updated on or after this ISO date or datetime (YYYY-MM-DD or RFC 3339).
`assignee_email`	No	Filter to incidents assigned to this email.
`updated_within`	No	Convenience alias for updated_from. Accepts "Nh" (hours), "Nd" (days), or "Nw" (weeks). Examples: "24h", "7d", "1w", "30d". Ignored if updated_from is explicitly set.
`requester_email`	No	Filter to incidents requested by this email.
`assigned_to_group`	No	Filter to incidents assigned to this group ID. Use swsd_list_groups to find the ID. NOTE: this is GROUP id, not user id.

Output Schema

TableJSON Schema

Name	Required	Description
`scan`	Yes	Honest accounting of what was scanned vs matched.
`incidents`	Yes
`pagination`	Yes
`applied_filters`	Yes	Echo of the filters applied to this query — empty object if none. Use this to reason about whether the result count reflects your filters or the tenant total. NOTE: assignee_email / requester_email are applied client-side; everything else is server-side.

Schema Changelog

Changes observed during successful MCP inspections.

Changed29 schema fields changedv2.3.1Aug 22, 2026

addedInput schema / properties / assignee_email / maxLength
```
Added value: +320
```
addedInput schema / properties / categories / items / maxLength
```
Added value: +500
```
addedInput schema / properties / categories / maxItems
```
Added value: +100
```

addedInput schema / properties / created_from / anyOf

Added value: +[
+  {
+    "format": "date",
+    "maxLength": 64,
+    "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
+    "type": "string"
+  },
+  {
+    "format": "date-time",
+    "maxLength": 64,
+    "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
+    "type": "string"
+  }
+]

removedInput schema / properties / created_from / minLength
```
Removed value: -10
```
removedInput schema / properties / created_from / type
```
Removed value: -"string"
```

addedInput schema / properties / created_to / anyOf

Added value: +[
+  {
+    "format": "date",
+    "maxLength": 64,
+    "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
+    "type": "string"
+  },
+  {
+    "format": "date-time",
+    "maxLength": 64,
+    "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
+    "type": "string"
+  }
+]

removedInput schema / properties / created_to / minLength
```
Removed value: -10
```
removedInput schema / properties / created_to / type
```
Removed value: -"string"
```
addedInput schema / properties / departments / items / maxLength
```
Added value: +500
```
addedInput schema / properties / departments / maxItems
```
Added value: +100
```
addedInput schema / properties / priorities / items / maxLength
```
Added value: +500
```
addedInput schema / properties / priorities / maxItems
```
Added value: +100
```
addedInput schema / properties / query / maxLength
```
Added value: +2000
```
addedInput schema / properties / requester_email / maxLength
```
Added value: +320
```
addedInput schema / properties / sites / items / maxLength
```
Added value: +500
```
addedInput schema / properties / sites / maxItems
```
Added value: +100
```
addedInput schema / properties / state_is_not / items / maxLength
```
Added value: +500
```
addedInput schema / properties / state_is_not / maxItems
```
Added value: +100
```
addedInput schema / properties / states / items / maxLength
```
Added value: +500
```
addedInput schema / properties / states / maxItems
```
Added value: +100
```

addedInput schema / properties / updated_from / anyOf

Added value: +[
+  {
+    "format": "date",
+    "maxLength": 64,
+    "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
+    "type": "string"
+  },
+  {
+    "format": "date-time",
+    "maxLength": 64,
+    "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
+    "type": "string"
+  }
+]

removedInput schema / properties / updated_from / minLength
```
Removed value: -10
```
removedInput schema / properties / updated_from / type
```
Removed value: -"string"
```

addedInput schema / properties / updated_to / anyOf

Added value: +[
+  {
+    "format": "date",
+    "maxLength": 64,
+    "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
+    "type": "string"
+  },
+  {
+    "format": "date-time",
+    "maxLength": 64,
+    "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
+    "type": "string"
+  }
+]

removedInput schema / properties / updated_to / minLength
```
Removed value: -10
```
removedInput schema / properties / updated_to / type
```
Removed value: -"string"
```
addedInput schema / properties / updated_within / maxLength
```
Added value: +4
```
addedInput schema / properties / updated_within / pattern
```
Added value: +"^[1-9]\\d{0,2}[hdw]$"
```

First observedv2.1.0May 28, 2026

TDQS

A4.6/5.0

Behavior4/5

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

Annotations already indicate read-only and idempotent. The description adds valuable behavior like client-side application of assignee_email/requester_email (with verification date) and the note that other filters narrow server-side. It doesn't over-explain but covers critical pitfalls.

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?

The description is moderately long but every sentence adds value. First sentence states purpose, then return format, then filter semantics, then crucial client-side note. Slightly verbose but well-structured and front-loaded.

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

Completeness5/5

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

For a tool with 19 parameters and an output schema, the description covers return format, points to detail tool, explains filter semantics, client-side caveats, and indexing-time behavior. Nothing essential is missing for an agent to use it correctly.

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

Parameters4/5

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

Schema coverage is 100%, so baseline is 3. The description adds extra semantics: repeated-key array OR-ed behavior, client-side vs server-side filtering, and the async-indexing caveat for query. This goes beyond schema descriptions.

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

Purpose5/5

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

The description clearly states the tool lists SWSD incidents with structured filters and pagination, and explicitly differentiates it from swsd_get_incident (full detail) and swsd_list_my_incidents. The verb 'list' + resource 'SWSD incidents' is precise.

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

Usage Guidelines5/5

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

Explicitly instructs to call swsd_get_incident for full detail, explains client-side vs server-side filtering behavior, and distinguishes when to use this vs alternatives. Provides concrete guidance on filter semantics and caveats.

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

Install Server