Skip to main content
Glama
Sign In
OpenProject CE MCP

OpenProject CE MCP

by jtauschl
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

list_work_package_attachments

Read-onlyIdempotent

List all attachments on a work package, optionally summing total file size or returning PNG/JPEG/GIF/WebP images inline for the model to view.

Instructions

List attachments on a work package.

include_total_size=true sums file_size_bytes across every attachment (independent of limit/offset); OpenProject's attachments endpoint always returns the full list in one response, so this costs no extra request in the common case. Null if file_size_bytes is hidden by server configuration, rather than leaking it indirectly through a sum.

include_images=true also reads the listed PNG/JPEG/GIF/WebP attachments and returns them as images the model can see, appended after the list. One shared byte budget covers the whole call (OPENPROJECT_ATTACHMENT_CONTENT_MAX_BYTES, 5 MB by default), taken in listing order; every attachment that was not inlined is reported in images with its reason. Use get_attachment_content for one specific attachment, or for text content.

Input Schema

NameRequiredDescriptionDefault
limitNoPage size, capped at OPENPROJECT_MAX_PAGE_SIZE.
offsetNo1-based page number; pass the previous result's next_offset.
selectNoFields to return; a requested unset field comes back as null. Allowed: author, container_id, container_type, content_type, created_at, description, download_url, file_name, file_size_bytes, id, status, title.
include_imagesNo
work_package_idYesWork package id (e.g. 952) or display id (e.g. "PROJ-51"), not the bare number 51.
include_total_sizeNo

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. Changed1 schema field changedv0.2.3
    • changedOutput schema / (root)
      Previous value: -{
-  "$defs": {
-    "AttachmentSummary": {
-      "properties": {
-        "author": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "title": "Author"
-        },
-        "container_id": {
-          "anyOf": [
-            {
-              "type": "integer"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "title": "Container Id"
-        },
-        "container_type": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "title": "Container Type"
-        },
-        "content_type": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "title": "Content Type"
-        },
-        "created_at": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "title": "Created At"
-        },
-        "description": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "title": "Description"
-        },
-        "download_url": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "title": "Download Url"
-        },
-        "file_name": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "title": "File Name"
-        },
-        "file_size": {
-          "anyOf": [
-            {
-              "type": "integer"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "title": "File Size"
-        },
-        "id": {
-          "title": "Id",
-          "type": "integer"
-        },
-        "status": {
-          "anyOf": [
-            {
-              "type": "string"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "title": "Status"
-        },
-        "title": {
-          "title": "Title",
-          "type": "string"
-        },
-        "url": {
-          "title": "Url",
-          "type": "string"
-        }
-      },
-      "required": [
-        "id",
-        "title",
-        "file_name",
-        "file_size",
-        "description",
-        "content_type",
-        "status",
-        "author",
-        "container_type",
-        "container_id",
-        "created_at",
-        "download_url",
-        "url"
-      ],
-      "title": "AttachmentSummary",
-      "type": "object"
-    }
-  },
-  "properties": {
-    "count": {
-      "title": "Count",
-      "type": "integer"
-    },
-    "results": {
-      "items": {
-        "$ref": "#/$defs/AttachmentSummary"
-      },
-      "title": "Results",
-      "type": "array"
-    }
-  },
-  "required": [
-    "count",
-    "results"
-  ],
-  "title": "AttachmentListResult",
-  "type": "object"
-}New value: +null
  7. First observedv0.2.2

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds substantial context: the endpoint returns the full list so summing costs no extra request, the sum is null rather than leaking a hidden file size, and image inlining draws from a shared 5 MB budget in listing order with each skipped attachment reported with a reason. These are genuine behavioral traits an agent could not infer from annotations.

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 one sentence, and each subsequent paragraph maps to a capability an agent might invoke. The include_images paragraph is dense but every clause (budget, default, order, skipped-attachment reporting) carries operational weight.

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 still explains the notable return behaviors (the images array, per-attachment skip reasons, null total size). It does not describe the base list item shape, but the select parameter enumerates those fields in the schema.

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

Parameters5/5

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

The two flags with no schema description (include_images, include_total_size) get full semantics including defaults, budget, ordering, and null behavior. That meaningfully exceeds the 67% schema coverage where those parameters are bare booleans.

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?

Opens with a specific verb and resource ('List attachments on a work package') that is unmistakably distinct from the content-fetching siblings, and later names get_attachment_content as the single-attachment path. An agent knows exactly what this returns without opening the 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?

Explicitly routes to get_attachment_content 'for one specific attachment, or for text content', which is the key alternative. It also conditions the two optional flags on what the caller wants (total size, inlined images). It stops short of stating outright exclusions, but the alternative selection is clear.

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