OpenProject CE MCP Server

Overview Schema Source Related Servers Discussions Admin

List work packages

list_work_packages

Read-onlyIdempotent

List and filter OpenProject work packages by assignee, status, due date, project, or custom criteria to find overdue, unassigned, or assigned tasks. Supports paging, grouping, and server-side totals.

Instructions

List work packages with structured filters — the workhorse read tool.

Handles "assigned to me", "overdue" via parameters, not separate tools: overdue → due_before=<today>; unassigned → assignee=['none']; nearly done → percentage_done_min=80; subtasks of a ticket → parent_id=<id>.

Returns the standard list envelope: rows plus pagination, plus groups when group_by is set and sums when show_sums is set — both computed server-side over the whole filtered set, independent of paging; never re-add them from one page's rows.

Pitfalls: returns open work packages only unless status_scope or status_ids is given (status_ids overrides status_scope), so say so when reporting counts. Status, type, priority and version ids come from get_project_metadata; user ids (assignee, author, responsible, watcher) from search_principals — never guess either. Date filters take YYYY-MM-DD, both bounds inclusive.

For text lookups use search_work_packages; for one work package's description, custom fields and children use get_work_package.

Input Schema

Name	Required	Description	Default
`page`	No	1-based page number.
`query`	No	Free text, AND-combined with other filters; matches subject, description and comments.
`author`	No	Author (creator) user ids, or 'me' ('none' not valid).
`project`	No	Numeric project id or identifier (URL slug); from list_projects. Omit for a cross-project view.
`sort_by`	No	Sort as snake_case pairs, e.g. [['due_date','asc'],['priority','desc']]. An unknown key fails, listing the allowed set.
`watcher`	No	Watched by these user ids, or 'me'.
`assignee`	No	Assignee filter: numeric user ids, 'me', or 'none' for unassigned work. get_instance_info gives the current user.
`group_by`	No	Group the full filtered set by one snake_case column (e.g. 'status'). Counts in `groups` cover every page.
`type_ids`	No	Type ids (Task, Bug…).
`due_after`	No	Due on/after.
`fetch_all`	No	Aggregate every page into one result instead of page 1. Capped at 500 items (noted when it bites); mutually exclusive with page.
`page_size`	No	Results per page (max 100).
`parent_id`	No	Direct children only. Mutually exclusive with top_level_only; use ancestor_id for the whole subtree.
`show_sums`	No	Server-computed totals (estimated/remaining/spent hours, story points) over the full filtered set; never add up pages yourself.
`due_before`	No	Due on/before.
`sprint_ids`	No	Sprint ids; from list_sprints.
`status_ids`	No	Exact status ids. Overrides status_scope.
`ancestor_id`	No	Whole subtree, any depth (parent_id is one level only).
`raw_filters`	No	Escape hatch for untyped filters, e.g. custom fields: [{'name': 'customField12', 'operator': '=', 'values': ['4']}]. Field names and option ids come from get_work_package_schema.
`responsible`	No	Accountable user ids, 'me', or 'none' (no accountable user).
`start_after`	No	Starts on/after.
`version_ids`	No	Version ids.
`priority_ids`	No	Priority ids.
`start_before`	No	Starts on/before.
`status_scope`	No	Status bucket: 'open' (default), 'closed' or 'all'. Ignored when status_ids is given.	open
`created_since`	No	Created on/after.
`created_until`	No	Created on/before.
`updated_since`	No	Changed on/after.
`updated_until`	No	Changed on/before.
`top_level_only`	No	Work packages with no parent (excludes every subtask).
`milestones_only`	No	Only milestone-type work packages; intersected with type_ids when both are given.
`percentage_done_max`	No	Maximum progress percent.
`percentage_done_min`	No	Minimum progress percent.

Output Schema

Name	Required	Description	Default
`sums`	No
`items`	No
`notes`	No
`groups`	No
`pagination`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed65 schema fields changedv0.4.0Oct 24, 2026

changedInput schema / properties / created_since / description

Previous value: -"Created on/after, ISO date."New value: +"Created on/after."

addedInput schema / properties / created_until

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Created on/before."
+}

changedInput schema / properties / due_after / description

Previous value: -"Due on/after, ISO date."New value: +"Due on/after."

changedInput schema / properties / due_before / description

Previous value: -"Due on/before, ISO date."New value: +"Due on/before."

changedInput schema / properties / start_after / description

Previous value: -"Starts on/after, ISO date."New value: +"Starts on/after."

changedInput schema / properties / start_before / description

Previous value: -"Starts on/before, ISO date."New value: +"Starts on/before."

changedInput schema / properties / updated_since / description

Previous value: -"Changed on/after, ISO date."New value: +"Changed on/after."

addedInput schema / properties / updated_until

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Changed on/before."
+}

changedOutput schema / properties / groups / anyOf

Previous value: -[
-  {
-    "items": {
-      "description": "A server-side group bucket, computed over the full filtered set.",
-      "properties": {
-        "count": {
-          "default": 0,
-          "description": "Records in this group across all pages.",
-          "type": "integer"
-        },
-        "sums": {
-          "anyOf": [
-            {
-              "additionalProperties": {
-                "type": "number"
-              },
-              "type": "object"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "description": "Per-group sums when show_sums was requested."
-        },
-        "value": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "description": "Group value, e.g. a status name."
-        }
-      },
-      "type": "object"
-    },
-    "type": "array"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "items": {
+      "properties": {
+        "count": {
+          "type": "integer"
+        },
+        "sums": {
+          "anyOf": [
+            {
+              "additionalProperties": {
+                "type": "number"
+              },
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "value": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      },
+      "type": "object"
+    },
+    "type": "array"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / groups / default
```
Removed value: -null
```

removedOutput schema / properties / groups / description

Removed value: -"Present only when group_by was requested."

removedOutput schema / properties / items / description
```
Removed value: -"The page of results."
```

removedOutput schema / properties / items / items / description

Removed value: -"Compact work-package row for list results."

changedOutput schema / properties / items / items / properties / assignee / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "description": "A reference to another resource. Canonical output shape.",
-    "properties": {
-      "id": {
-        "anyOf": [
-          {
-            "type": "integer"
-          },
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Resource id."
-      },
-      "name": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Human-readable name."
-      }
-    },
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "id": {
+        "type": [
+          "integer",
+          "string",
+          "null"
+        ]
+      },
+      "name": {
+        "type": [
+          "string",
+          "null"
+        ]
+      }
+    },
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / items / items / properties / assignee / default
```
Removed value: -null
```
removedOutput schema / properties / items / items / properties / assignee / description
```
Removed value: -"Assigned user or group."
```

removedOutput schema / properties / items / items / properties / display_id / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

removedOutput schema / properties / items / items / properties / display_id / default
```
Removed value: -null
```

removedOutput schema / properties / items / items / properties / display_id / description

Removed value: -"Human-facing id as the instance renders it. Matches the numeric id unless the instance uses semantic identifiers (17.x, e.g. 'PROJ-42'); null when the instance predates it."

addedOutput schema / properties / items / items / properties / display_id / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / items / items / properties / due_date / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

removedOutput schema / properties / items / items / properties / due_date / default
```
Removed value: -null
```
removedOutput schema / properties / items / items / properties / due_date / description
```
Removed value: -"ISO date (YYYY-MM-DD)."
```
addedOutput schema / properties / items / items / properties / due_date / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / items / items / properties / id / anyOf

Removed value: -[
-  {
-    "type": "integer"
-  },
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

removedOutput schema / properties / items / items / properties / id / default
```
Removed value: -null
```
removedOutput schema / properties / items / items / properties / id / description
```
Removed value: -"Work package id."
```
addedOutput schema / properties / items / items / properties / id / type
```
Added value: +[
+  "integer",
+  "string",
+  "null"
+]
```
removedOutput schema / properties / items / items / properties / percentage_done / anyOf
```
Removed value: -[
-  {
-    "type": "integer"
-  },
-  {
-    "type": "null"
-  }
-]
```
removedOutput schema / properties / items / items / properties / percentage_done / default
```
Removed value: -null
```
removedOutput schema / properties / items / items / properties / percentage_done / description
```
Removed value: -"Progress, 0-100."
```
addedOutput schema / properties / items / items / properties / percentage_done / type
```
Added value: +[
+  "integer",
+  "null"
+]
```

changedOutput schema / properties / items / items / properties / priority / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "description": "A reference to another resource. Canonical output shape.",
-    "properties": {
-      "id": {
-        "anyOf": [
-          {
-            "type": "integer"
-          },
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Resource id."
-      },
-      "name": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Human-readable name."
-      }
-    },
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "id": {
+        "type": [
+          "integer",
+          "string",
+          "null"
+        ]
+      },
+      "name": {
+        "type": [
+          "string",
+          "null"
+        ]
+      }
+    },
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / items / items / properties / priority / default
```
Removed value: -null
```
removedOutput schema / properties / items / items / properties / priority / description
```
Removed value: -"Priority."
```

changedOutput schema / properties / items / items / properties / project / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "description": "A reference to another resource. Canonical output shape.",
-    "properties": {
-      "id": {
-        "anyOf": [
-          {
-            "type": "integer"
-          },
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Resource id."
-      },
-      "name": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Human-readable name."
-      }
-    },
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "id": {
+        "type": [
+          "integer",
+          "string",
+          "null"
+        ]
+      },
+      "name": {
+        "type": [
+          "string",
+          "null"
+        ]
+      }
+    },
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / items / items / properties / project / default
```
Removed value: -null
```
removedOutput schema / properties / items / items / properties / project / description
```
Removed value: -"Owning project."
```

removedOutput schema / properties / items / items / properties / start_date / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

removedOutput schema / properties / items / items / properties / start_date / default
```
Removed value: -null
```
removedOutput schema / properties / items / items / properties / start_date / description
```
Removed value: -"ISO date (YYYY-MM-DD)."
```
addedOutput schema / properties / items / items / properties / start_date / type
```
Added value: +[
+  "string",
+  "null"
+]
```

changedOutput schema / properties / items / items / properties / status / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "description": "A reference to another resource. Canonical output shape.",
-    "properties": {
-      "id": {
-        "anyOf": [
-          {
-            "type": "integer"
-          },
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Resource id."
-      },
-      "name": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Human-readable name."
-      }
-    },
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "id": {
+        "type": [
+          "integer",
+          "string",
+          "null"
+        ]
+      },
+      "name": {
+        "type": [
+          "string",
+          "null"
+        ]
+      }
+    },
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / items / items / properties / status / default
```
Removed value: -null
```
removedOutput schema / properties / items / items / properties / status / description
```
Removed value: -"Status."
```

removedOutput schema / properties / items / items / properties / subject / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

removedOutput schema / properties / items / items / properties / subject / default
```
Removed value: -null
```
removedOutput schema / properties / items / items / properties / subject / description
```
Removed value: -"Subject line."
```
addedOutput schema / properties / items / items / properties / subject / type
```
Added value: +[
+  "string",
+  "null"
+]
```

changedOutput schema / properties / items / items / properties / type / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "description": "A reference to another resource. Canonical output shape.",
-    "properties": {
-      "id": {
-        "anyOf": [
-          {
-            "type": "integer"
-          },
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Resource id."
-      },
-      "name": {
-        "anyOf": [
-          {
-            "type": "string"
-          },
-          {
-            "type": "null"
-          }
-        ],
-        "default": null,
-        "description": "Human-readable name."
-      }
-    },
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "id": {
+        "type": [
+          "integer",
+          "string",
+          "null"
+        ]
+      },
+      "name": {
+        "type": [
+          "string",
+          "null"
+        ]
+      }
+    },
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / items / items / properties / type / default
```
Removed value: -null
```
removedOutput schema / properties / items / items / properties / type / description
```
Removed value: -"Work package type."
```

removedOutput schema / properties / items / items / properties / updated_at / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

removedOutput schema / properties / items / items / properties / updated_at / default
```
Removed value: -null
```
removedOutput schema / properties / items / items / properties / updated_at / description
```
Removed value: -"ISO 8601 UTC timestamp."
```
addedOutput schema / properties / items / items / properties / updated_at / type
```
Added value: +[
+  "string",
+  "null"
+]
```
removedOutput schema / properties / notes / default
```
Removed value: -null
```

removedOutput schema / properties / notes / description

Removed value: -"Degradation markers: capped aggregations, unavailable modules, …"

removedOutput schema / properties / pagination / description
```
Removed value: -"Total/page/page_size/has_more."
```
removedOutput schema / properties / pagination / properties / has_more / description
```
Removed value: -"True when further pages exist."
```
removedOutput schema / properties / pagination / properties / page / description
```
Removed value: -"1-based page number of this result."
```
removedOutput schema / properties / pagination / properties / page_size / description
```
Removed value: -"Records requested per page."
```
removedOutput schema / properties / pagination / properties / total / description
```
Removed value: -"Total matching records on the server."
```
removedOutput schema / properties / sums / default
```
Removed value: -null
```

removedOutput schema / properties / sums / description

Removed value: -"Present only when show_sums was requested."

Changed2 schema fields changedv0.3.3Oct 3, 2026

addedInput schema / properties / sprint_ids

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "type": "integer"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Sprint ids; from list_sprints."
+}

changedInput schema / properties / version_ids / description

Previous value: -"Version / sprint ids."New value: +"Version ids."

Changed28 schema fields changedv0.3.2Sep 24, 2026

changedInput schema / properties / ancestor_id / description

Previous value: -"Everything in this work package's subtree at any depth, unlike parent_id which is one level only."New value: +"Whole subtree, any depth (parent_id is one level only)."

changedInput schema / properties / assignee / description

Previous value: -"Assignee filter: numeric user ids, the single value 'me', or the single value 'none' for unassigned work. Ids come from search_principals; get_instance_info gives the current user."New value: +"Assignee filter: numeric user ids, 'me', or 'none' for unassigned work. get_instance_info gives the current user."

changedInput schema / properties / author / description

Previous value: -"Author (creator) user ids, or 'me'. 'none' is not valid here."New value: +"Author (creator) user ids, or 'me' ('none' not valid)."

changedInput schema / properties / created_since / description

Previous value: -"Created on or after this ISO date (YYYY-MM-DD)."New value: +"Created on/after, ISO date."

changedInput schema / properties / due_after / description

Previous value: -"Due on or after this ISO date (YYYY-MM-DD)."New value: +"Due on/after, ISO date."

changedInput schema / properties / due_before / description

Previous value: -"Due on or before this ISO date (YYYY-MM-DD)."New value: +"Due on/before, ISO date."

changedInput schema / properties / fetch_all / description

Previous value: -"Aggregate every page into one result instead of returning page 1. Capped at 500 items with a note when the cap bites; mutually exclusive with page."New value: +"Aggregate every page into one result instead of page 1. Capped at 500 items (noted when it bites); mutually exclusive with page."

changedInput schema / properties / group_by / description

Previous value: -"Group the full filtered set by one snake_case column (e.g. 'status', 'assignee'). Counts in `groups` cover every page, not just this one."New value: +"Group the full filtered set by one snake_case column (e.g. 'status'). Counts in `groups` cover every page."

changedInput schema / properties / milestones_only / description

Previous value: -"Only milestone-type work packages. Resolved against this instance's own types (no hardcoded ids) and intersected with type_ids when both are given."New value: +"Only milestone-type work packages; intersected with type_ids when both are given."

changedInput schema / properties / parent_id / description

Previous value: -"Direct children of this work package only. Mutually exclusive with top_level_only; use ancestor_id for the whole subtree."New value: +"Direct children only. Mutually exclusive with top_level_only; use ancestor_id for the whole subtree."

changedInput schema / properties / percentage_done_max / description

Previous value: -"Maximum progress percentage, 0-100."New value: +"Maximum progress percent."

changedInput schema / properties / percentage_done_min / description

Previous value: -"Minimum progress percentage, 0-100."New value: +"Minimum progress percent."

changedInput schema / properties / priority_ids / description

Previous value: -"Priority ids; from get_project_metadata. Never guess these — priority ids differ per instance."New value: +"Priority ids."

changedInput schema / properties / project / description

Previous value: -"Numeric project id or project identifier (URL slug) to scope the query. Both come from list_projects. Omit for a cross-project view."New value: +"Numeric project id or identifier (URL slug); from list_projects. Omit for a cross-project view."

changedInput schema / properties / query / description

Previous value: -"Optional free text, AND-combined with every other filter. Matches subject, description and comments. For text-only lookups prefer search_work_packages."New value: +"Free text, AND-combined with other filters; matches subject, description and comments."

changedInput schema / properties / raw_filters / description

Previous value: -"Escape hatch for filters this tool does not type, most importantly custom fields: [{'name': 'customField12', 'operator': '=', 'values': ['4']}]. Custom field names and option ids come from get_work_package_schema."New value: +"Escape hatch for untyped filters, e.g. custom fields: [{'name': 'customField12', 'operator': '=', 'values': ['4']}]. Field names and option ids come from get_work_package_schema."

changedInput schema / properties / responsible / description

Previous value: -"Accountable user ids, 'me', or 'none' for no accountable user."New value: +"Accountable user ids, 'me', or 'none' (no accountable user)."

changedInput schema / properties / show_sums / description

Previous value: -"Ask the server for totals (estimated/remaining/spent hours, story points) over the full filtered set. Never add up pages yourself."New value: +"Server-computed totals (estimated/remaining/spent hours, story points) over the full filtered set; never add up pages yourself."

changedInput schema / properties / sort_by / description

Previous value: -"Server-side sort as snake_case pairs, e.g. [['due_date','asc'],['priority','desc']]. An unknown key fails with the allowed set listed."New value: +"Sort as snake_case pairs, e.g. [['due_date','asc'],['priority','desc']]. An unknown key fails, listing the allowed set."

changedInput schema / properties / start_after / description

Previous value: -"Starts on or after this ISO date (YYYY-MM-DD)."New value: +"Starts on/after, ISO date."

changedInput schema / properties / start_before / description

Previous value: -"Starts on or before this ISO date (YYYY-MM-DD)."New value: +"Starts on/before, ISO date."

changedInput schema / properties / status_ids / description

Previous value: -"Exact status ids. **Overrides status_scope** — the two never fight. Ids come from get_project_metadata."New value: +"Exact status ids. **Overrides status_scope**."

changedInput schema / properties / status_scope / description

Previous value: -"Status bucket: 'open' (default), 'closed' or 'all'. An explicit status filter is always sent, so the server's implicit open-only default never silently applies. Ignored when status_ids is given."New value: +"Status bucket: 'open' (default), 'closed' or 'all'. Ignored when status_ids is given."

changedInput schema / properties / top_level_only / description

Previous value: -"Only work packages that have no parent. Excludes every subtask."New value: +"Work packages with no parent (excludes every subtask)."

changedInput schema / properties / type_ids / description

Previous value: -"Work package type ids (Task, Bug…); from get_project_metadata."New value: +"Type ids (Task, Bug…)."

changedInput schema / properties / updated_since / description

Previous value: -"Last changed on or after this ISO date (YYYY-MM-DD)."New value: +"Changed on/after, ISO date."

changedInput schema / properties / version_ids / description

Previous value: -"Version / sprint ids; from get_project_metadata."New value: +"Version / sprint ids."

changedInput schema / properties / watcher / description

Previous value: -"Work packages watched by these user ids, or 'me'."New value: +"Watched by these user ids, or 'me'."

First observedv0.1.0Aug 12, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Beyond the read-only annotations, it discloses critical behavior: only open work packages are returned unless `status_scope` or `status_ids` is supplied, and `status_ids` overrides `status_scope`. It also explains that `groups` and `sums` are server-computed over the whole filtered set rather than per page, which prevents incorrect aggregation by the agent.

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

Conciseness5/5

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

The description is front-loaded with purpose and usage recipes, then follows with return-shape and pitfalls. Despite covering a 33-parameter tool, every paragraph carries actionable information without filler.

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?

Given the rich annotations, full schema coverage, and an output schema, the description fills the remaining gaps: response envelope, grouped/summed behavior, default open-status scope, date format, and sibling tool routing. Nothing essential for correct invocation appears missing.

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 already 100%, so the baseline would be 3, but the description adds useful semantics: date filters are inclusive and use YYYY-MM-DD, identity/type/priority/version IDs must come from specific metadata tools, and `status_ids` takes precedence over `status_scope`. Some recipes repeat schema-level details, but the cross-parameter precedence and ID-source guidance add real value.

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 states a specific verb and resource — “List work packages” — and immediately positions it as the “workhorse read tool” for structured filtering. It clearly distinguishes itself from text search and single-package retrieval by naming `search_work_packages` and `get_work_package` as alternatives.

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?

It gives explicit mappings from common intents to parameters: assigned-to-me, overdue, unassigned, nearly done, and subtasks. It also states when to use `search_work_packages` for text lookups versus `get_work_package` for descriptions and children, leaving little ambiguity.

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

Deploy Server