Skip to main content
Glama
Sign In
OpenProject CE MCP

OpenProject CE MCP

by jtauschl
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

get_work_packages

Read-onlyIdempotent

Fetch multiple work packages by internal or display IDs in one batch call and return per-item results, reporting failed fetches individually.

Instructions

Get several work packages by id in one batch call.

Fetches work packages in parallel and returns per-item results. Failed fetches are reported individually without stopping the batch. Maximum 100 IDs per batch.

ids: internal ids (e.g., 952) or display_ids (e.g., "PROJ-51"), not UI display numbers. Duplicate IDs are automatically deduplicated.

select restricts each result's work_package to the given fields (e.g. ["id", "subject", "status"]); an invalid name returns the allowed set. The id/success/error fields on each result are always included regardless of select, so you can still tell which items succeeded; listing success or error in select is accepted and changes nothing, while id doubles as a selectable work_package field.

For batches with many full-detail items, set text_limit and/or select proactively; an unbounded batch of large work packages can exceed the tool-result size limit and get redirected to a file.

Each item's work_package carries the same custom_fields/custom_comments shape and caps as get_work_package; see list_work_packages's docstring for the full details (raw-key values, per-field caps, and the OPENPROJECT_HIDE_CUSTOM_FIELDS key-only hide-matching asymmetry). With many items, an unbounded custom_fields/custom_comments per item adds to the same size-limit risk text_limit/select address above.

Input Schema

NameRequiredDescriptionDefault
idsYes
selectNoFields to return; a requested unset field comes back as null. Allowed: ancestors, ancestors_truncated, assignee, author, category, children, children_truncated, created_at, custom_comments, custom_comments_truncated, custom_fields, custom_fields_truncated, derived_due_date, derived_estimated_time, derived_percentage_done, derived_remaining_time, derived_start_date, description, description_length, description_truncated, display_id, due_date, duration, error, estimated_time, has_project_attributes, id, ignore_non_working_days, lock_version, parent_display_id, parent_id, percentage_done, priority, project, project_phase, readonly, remaining_time, responsible, schedule_manually, spent_time, sprint, start_date, status, subject, success, target_versions, type, updated_at, version.
text_limitNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.4.4
  2. Removedv0.4.0
  3. Changed1 schema field changedv0.3.7
    • addedInput schema / additionalProperties
      Added value: +false
  4. Addedv0.3.3
  5. Removedv0.3.0
  6. Addedv0.2.3

TDQS

A4.2/5.0
Behavior5/5

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

Goes well beyond the readOnly/idempotent/destructive annotations: parallel fetching, per-item failure reporting without aborting the batch, deduplication, the 100-ID cap, the size-limit-to-file redirection, and the guarantee that id/success/error survive select. This is genuinely useful operational context an agent could not get from the structured fields.

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?

Front-loads the core purpose and batch limits, then layers select, text_limit, and custom_fields caveats in a logical order. It runs long and repeats the size-limit risk twice (once for text_limit/select, once for custom_fields), which is some redundancy.

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?

With no output schema, the description does the right thing by describing the per-item result shape (work_package plus id/success/error). It partly punts the custom_fields/custom_comments details to get_work_package's and list_work_packages's docstrings, which is a gap for an agent that only sees this definition.

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 only 33%, but the description compensates heavily: it explains that ids accepts internal ids or display_ids (explicitly not UI display numbers) and are deduplicated, and it details select's filtering behavior, always-included fields, and invalid-name fallback. text_limit's truncation semantics are only alluded to ('unbounded ... can exceed the size limit'), leaving that parameter underspecified.

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

Purpose4/5

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

States a specific verb and resource with distinguishing scope: 'Get several work packages by id in one batch call.' That clearly separates it from the singular get_work_package and the filter-based list_work_packages/search_work_packages, though it never names those siblings explicitly.

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?

Provides concrete operating guidance: 100-ID maximum, proactive use of text_limit/select for large batches, and the dedup behavior for duplicate IDs, plus the warning that unbounded batches get redirected to a file. It does not explicitly say when to prefer get_work_package or list_work_packages instead, which keeps it short of a 5.

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