Skip to main content
Glama

List work packages

list_work_packages
Read-onlyIdempotent

Query and filter OpenProject work packages by assignee, status, due date, project, or custom fields; returns paginated rows with optional groups and server-computed sums.

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.

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

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
pageNo1-based page number.
queryNoFree text, AND-combined with other filters; matches subject, description and comments.
authorNoAuthor (creator) user ids, or 'me' ('none' not valid).
projectNoNumeric project id or identifier (URL slug); from list_projects. Omit for a cross-project view.
sort_byNoSort as snake_case pairs, e.g. [['due_date','asc'],['priority','desc']]. An unknown key fails, listing the allowed set.
watcherNoWatched by these user ids, or 'me'.
assigneeNoAssignee filter: numeric user ids, 'me', or 'none' for unassigned work. get_instance_info gives the current user.
group_byNoGroup the full filtered set by one snake_case column (e.g. 'status'). Counts in `groups` cover every page.
type_idsNoType ids (Task, Bug…).
due_afterNoDue on/after, ISO date.
fetch_allNoAggregate every page into one result instead of page 1. Capped at 500 items (noted when it bites); mutually exclusive with page.
page_sizeNoResults per page (max 100).
parent_idNoDirect children only. Mutually exclusive with top_level_only; use ancestor_id for the whole subtree.
show_sumsNoServer-computed totals (estimated/remaining/spent hours, story points) over the full filtered set; never add up pages yourself.
due_beforeNoDue on/before, ISO date.
sprint_idsNoSprint ids; from list_sprints.
status_idsNoExact status ids. **Overrides status_scope**.
ancestor_idNoWhole subtree, any depth (parent_id is one level only).
raw_filtersNoEscape hatch for untyped filters, e.g. custom fields: [{'name': 'customField12', 'operator': '=', 'values': ['4']}]. Field names and option ids come from get_work_package_schema.
responsibleNoAccountable user ids, 'me', or 'none' (no accountable user).
start_afterNoStarts on/after, ISO date.
version_idsNoVersion ids.
priority_idsNoPriority ids.
start_beforeNoStarts on/before, ISO date.
status_scopeNoStatus bucket: 'open' (default), 'closed' or 'all'. Ignored when status_ids is given.open
created_sinceNoCreated on/after, ISO date.
updated_sinceNoChanged on/after, ISO date.
top_level_onlyNoWork packages with no parent (excludes every subtask).
milestones_onlyNoOnly milestone-type work packages; intersected with type_ids when both are given.
percentage_done_maxNoMaximum progress percent.
percentage_done_minNoMinimum progress percent.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
sumsNoPresent only when show_sums was requested.
itemsNoThe page of results.
notesNoDegradation markers: capped aggregations, unavailable modules, …
groupsNoPresent only when group_by was requested.
paginationYesTotal/page/page_size/has_more.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.3.3
    • 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."
  2. Changed28 schema fields changedv0.3.2
    • 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'."
  3. First observedv0.1.0

TDQS

A4.9/5.0
Behavior5/5

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

Annotations already cover readOnly/idempotent/destructive, but the description adds substantial behavior: it returns open WPs only unless status_scope/status_ids is set, status_ids overrides status_scope, and groups/sums are computed server-side over the full filtered set and must never be re-derived from one page. These are high-value traits not present in the annotations.

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?

Front-loads the core purpose, then scenarios, then return-envelope semantics, then pitfalls, then alternatives. Every sentence adds actionable information and there is no filler despite the long parameter list.

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?

An output schema exists so return values need not be explained, yet the description usefully clarifies envelope semantics (pagination/groups/sums) and id-sourcing prerequisites. For a 31-parameter read tool this is complete enough to call correctly without further context.

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 schema already documents all 31 params (baseline 3). The description goes beyond it by translating natural-language intents into specific parameter values and warning that ids must come from get_project_metadata/search_principals rather than being guessed.

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?

States a specific verb+resource ("List work packages with structured filters") and self-identifies as "the workhorse read tool". It explicitly distinguishes itself from siblings search_work_packages (text lookups) and get_work_package (single WP detail), so an agent can route without opening any schema.

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?

Maps concrete intents to parameters ("overdue" → due_before=<today>, "unassigned" → assignee=['none'], "nearly done" → percentage_done_min=80, subtasks → parent_id), noting these are handled by parameters rather than separate tools. It also names when to use alternate tools for text search and single-item retrieval.

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

Deploy Server

Other Tools