swsd-mcp

swsd_list_my_incidents

Read-onlyIdempotent

List incidents assigned to the authenticated user with optional state, priority, site, category, and date filters. Scopes results by the user's email because SWSD ignores assignee email filters.

Instructions

List incidents assigned to the authenticated user. Internally calls swsd_get_me to discover the user's email, then calls /incidents.json with the OTHER server-side filters applied (state, priority, etc.) and narrows the response client-side by assignee.email — because SWSD's /incidents.json endpoint silently ignores assignee_email / requester_email filters (verified 2026-05-08 against the live API: a fake email returns the entire tenant). The client-side filter is the only correct way to scope to a specific user. For broader queries use swsd_list_incidents with assigned_to_group=<group_id> (group filtering does work server-side).

Input 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).
`updated_within`	No	Convenience alias for updated_from: "Nh" is an exact hours-ago ISO timestamp; "Nd" and "Nw" use the UTC calendar date N days or N weeks ago. N must be 1-365. 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

Name	Required	Description
`scan`	Yes	Honest accounting of the client-side filter: what was scanned vs matched.
`incidents`	Yes
`pagination`	Yes
`assignee_email`	Yes	The authenticated user's email used as the assignee filter (applied client-side).
`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 and requester_email are applied client-side (post-fetch) because SWSD ignores them server-side.

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedv3.3.0Nov 5, 2026

changedInput schema / properties / updated_within / description

Previous value: -"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."New value: +"Convenience alias for updated_from: \"Nh\" is an exact hours-ago ISO timestamp; \"Nd\" and \"Nw\" use the UTC calendar date N days or N weeks ago. N must be 1-365. Ignored if updated_from is explicitly set."

changedOutput schema / properties / applied_filters / description

Previous value: -"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 is applied client-side (post-fetch) because SWSD ignores it server-side."New value: +"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 and requester_email are applied client-side (post-fetch) because SWSD ignores them server-side."

addedOutput schema / properties / pagination / properties / matched_total

Added value: +{
+  "anyOf": [
+    {
+      "maximum": 9007199254740991,
+      "minimum": 0,
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Total matching records, or null when unknown. After local filtering, known only when all candidate pages were scanned from page 1. Independent of display caps."
+}

changedOutput schema / properties / pagination / properties / total_scope / description

Previous value: -"Whether `total` reflects the filtered-set size, the tenant-wide size, or is unknown. 'filtered' = filter was applied AND total is present; 'tenant' = no filter AND total is present; 'unknown' = total absent."New value: +"Scope of the upstream `total`: 'upstream' = candidates before local filtering; 'filtered' = server-filtered count with no local filtering; 'tenant' = unfiltered count; 'unknown' = total absent. Sorting and display options are not filters."

changedOutput schema / properties / pagination / properties / total_scope / enum

Previous value: -[
-  "filtered",
-  "tenant",
-  "unknown"
-]New value: +[
+  "filtered",
+  "tenant",
+  "unknown",
+  "upstream"
+]

Changed7 schema fields changedv3.0.0Oct 4, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

changedInput schema / properties / created_from / anyOf

Previous 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"
-  }
-]New 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"
+  }
+]

changedInput schema / properties / created_to / anyOf

Previous 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"
-  }
-]New 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"
+  }
+]

changedInput schema / properties / requester_email / pattern

Previous value: -"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"New value: +"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"

changedInput schema / properties / updated_from / anyOf

Previous 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"
-  }
-]New 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"
+  }
+]

changedInput schema / properties / updated_to / anyOf

Previous 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"
-  }
-]New 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"
+  }
+]

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Changed28 schema fields changedv2.3.1Aug 22, 2026

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.5/5.0

Behavior5/5

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

Beyond the readOnly/idempotent annotations, the description discloses the internal two-call implementation (swsd_get_me then /incidents.json), a verified live-API defect where assignee_email/requester_email filters are silently ignored, and the resulting reliance on client-side assignee.email narrowing. That is exactly the kind of hidden behavior an agent needs to trust the results, and it includes a verification date rather than speculation.

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?

Purpose is front-loaded in the first sentence and each subsequent sentence carries distinct information (implementation, defect, alternative). The verification parenthetical and the "only correct way" self-justification make it longer than strictly necessary, though the content still earns most of its length.

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 an 18-parameter read tool with a full output schema and complete schema descriptions, the description covers the highest-risk unknown: that user scoping is client-side. The one material omission is the interaction between client-side filtering and pagination (whether a page can return fewer than per_page matches or whether results span pages), which matters for a self-scoped list.

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 the baseline is 3, but the description adds genuinely useful semantics: it clarifies that all filters other than assignee/requester email DO apply server-side ("state, priority, etc."), which tells the agent which parameters are actually honored. It stops short of naming individual parameters or warning how client-side narrowing interacts with page/per_page.

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?

"List incidents assigned to the authenticated user" gives a specific verb, resource, and implicit scope (self), and the closing sentence explicitly contrasts it with swsd_list_incidents for broader/group-scoped queries. An agent can distinguish this from the general incident lister without opening either schema.

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

Usage Guidelines4/5

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

It names the alternative explicitly (swsd_list_incidents with assigned_to_group=<group_id>) and states the condition that selects it, which is strong routing guidance. The gap is that the close sibling swsd_my_queue is never mentioned, so an agent must infer the boundary between "my incidents" and "my queue" on its own.

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

Deploy Server