OpenProject CE MCP Server

Overview Schema Source Related Servers Discussions Admin

Create work package

create_work_package

Create OpenProject work packages with pre-flight form validation that catches invalid statuses, missing required fields, or disallowed types before saving.

Instructions

Create a work package, validated through OpenProject's own form endpoint first.

Use it for new tasks, bugs, subtasks (parent_id) and milestones (date). The form pre-flight surfaces an invalid status, a missing required custom field or a disallowed type as structured violations with the allowed values, before anything is written.

Returns the created work package in full detail, including its new id, lock_version and resolved custom fields.

Pitfalls: type, status and priority take names or ids; versions, assignees and parents need numeric ids. Custom fields must exist on the schema — check get_work_package_schema when unsure.

To change it afterwards use update_work_package; to attach a file to an existing work package use upload_attachment.

Input Schema

Name	Required	Description
`date`	No	ISO date for a milestone (used instead of start_date/due_date). Passing both is rejected locally.
`type`	Yes	Type name or id ('Task', 'Bug', 'Milestone', or 7). Unknown or ambiguous names fail listing the valid values.
`notify`	No	Email notifications for this creation.
`sprint`	No	Numeric sprint id; from list_sprints. Omit to leave unset.
`status`	No	Status name or numeric id. Omit for the type's default; don't guess.
`project`	Yes	Numeric project id or identifier (URL slug); from list_projects.
`subject`	Yes	The title; must not be blank.
`version`	No	Numeric version id; from get_project_metadata.
`assignee`	No	Numeric user id ('me' isn't accepted in writes; get_instance_info gives the current user's id).
`due_date`	No	ISO date (YYYY-MM-DD); not valid on milestones.
`priority`	No	Priority name or id ('High', 'Normal', or 8). Omit for default.
`parent_id`	No	Work package id to create this as a child of.
`start_date`	No	ISO date (YYYY-MM-DD); not valid on milestones.
`description`	No	Body text in markdown.
`responsible`	No	Numeric id of the accountable person.
`story_points`	No	Story points as a non-negative integer.
`custom_fields`	No	Custom field writes keyed by wire key or display name: {'customField12': 'High'} or {'Severity': 'High'}. List/user/version fields take ids or names. Unknown keys fail listing the valid ones. get_work_package_schema shows what this project/type accepts.
`estimated_hours`	No	Estimate in hours, decimal (e.g. 7.5).
`remaining_hours`	No	Remaining work in hours, decimal.
`target_versions`	No	Target version ids. [] clears; omit to keep defaults. Multiple values need instance support. Mutually exclusive with version.
`attachment_paths`	No	Paths on the server's machine to attach. Over HTTP they must lie inside OPENPROJECT_MCP_UPLOAD_ROOT, and are refused when it is unset.

Output Schema

Name	Required	Description	Default
`id`	No
`date`	No
`type`	No
`notes`	No
`author`	No
`parent`	No
`sprint`	No
`status`	No
`project`	No
`subject`	No
`version`	No
`assignee`	No
`category`	No
`due_date`	No
`priority`	No
`available`	No
`created_at`	No
`display_id`	No
`start_date`	No
`updated_at`	No
`description`	No
`responsible`	No
`spent_hours`	No
`lock_version`	No
`story_points`	No
`custom_fields`	No
`project_phase`	No
`estimated_hours`	No
`percentage_done`	No
`remaining_hours`	No
`target_versions`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed128 schema fields changedv0.4.0Oct 24, 2026

changedInput schema / properties / attachment_paths / description

Previous value: -"Local file paths to attach (stdio transport only — the server must share your filesystem)."New value: +"Paths on the server's machine to attach. Over HTTP they must lie inside OPENPROJECT_MCP_UPLOAD_ROOT, and are refused when it is unset."

removedOutput schema / description

Removed value: -"Detail projection plus the milestone ``date`` field.\n\nMilestone types carry a single ``date`` instead of ``start_date``/\n``due_date``; both shapes are surfaced so a caller never has to guess."

changedOutput schema / 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 / assignee / default
```
Removed value: -null
```
removedOutput schema / properties / assignee / description
```
Removed value: -"Assigned user or group."
```

changedOutput schema / properties / author / 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 / author / default
```
Removed value: -null
```
removedOutput schema / properties / author / description
```
Removed value: -"Creating user."
```
removedOutput schema / properties / available / default
```
Removed value: -null
```

removedOutput schema / properties / available / description

Removed value: -"Feature availability for this WP: dev links, meetings, files."

changedOutput schema / properties / category / 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 / category / default
```
Removed value: -null
```
removedOutput schema / properties / category / description
```
Removed value: -"Category."
```

removedOutput schema / properties / created_at / anyOf

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

removedOutput schema / properties / created_at / default
```
Removed value: -null
```
removedOutput schema / properties / created_at / description
```
Removed value: -"ISO 8601 UTC timestamp."
```
addedOutput schema / properties / created_at / type
```
Added value: +[
+  "string",
+  "null"
+]
```
removedOutput schema / properties / custom_fields / description
```
Removed value: -"Always a list; empty when none are set."
```
removedOutput schema / properties / custom_fields / items / description
```
Removed value: -"Canonical custom-field read shape."
```
removedOutput schema / properties / custom_fields / items / properties / key / description
```
Removed value: -"Wire key, e.g. 'customField12'."
```

removedOutput schema / properties / custom_fields / items / properties / name / anyOf

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

removedOutput schema / properties / custom_fields / items / properties / name / default
```
Removed value: -null
```
removedOutput schema / properties / custom_fields / items / properties / name / description
```
Removed value: -"Display name, e.g. 'Severity'."
```
addedOutput schema / properties / custom_fields / items / properties / name / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / custom_fields / items / properties / type / anyOf

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

removedOutput schema / properties / custom_fields / items / properties / type / default
```
Removed value: -null
```
removedOutput schema / properties / custom_fields / items / properties / type / description
```
Removed value: -"Schema type, e.g. 'list', 'string'."
```
addedOutput schema / properties / custom_fields / items / properties / type / type
```
Added value: +[
+  "string",
+  "null"
+]
```
removedOutput schema / properties / custom_fields / items / properties / value / default
```
Removed value: -null
```
removedOutput schema / properties / custom_fields / items / properties / value / description
```
Removed value: -"Scalar value or resolved name(s)."
```

changedOutput schema / properties / custom_fields / items / properties / value_ids / anyOf

Previous value: -[
-  {
-    "items": {
-      "anyOf": [
-        {
-          "type": "integer"
-        },
-        {
-          "type": "string"
-        }
-      ]
-    },
-    "type": "array"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "items": {
+      "type": [
+        "integer",
+        "string"
+      ]
+    },
+    "type": "array"
+  },
+  {
+    "type": "null"
+  }
+]

removedOutput schema / properties / custom_fields / items / properties / value_ids / default
```
Removed value: -null
```
removedOutput schema / properties / custom_fields / items / properties / value_ids / description
```
Removed value: -"Ids for list/user/version custom fields."
```

removedOutput schema / properties / date / anyOf

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

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

removedOutput schema / properties / date / description

Removed value: -"Milestone date (ISO YYYY-MM-DD); null for non-milestones."

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

removedOutput schema / properties / description / anyOf

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

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

removedOutput schema / properties / description / description

Removed value: -"Description as markdown (raw); html is dropped."

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

removedOutput schema / properties / display_id / anyOf

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

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

removedOutput schema / 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 / display_id / type
```
Added value: +[
+  "string",
+  "null"
+]
```

removedOutput schema / properties / due_date / anyOf

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

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

removedOutput schema / properties / estimated_hours / anyOf

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

removedOutput schema / properties / estimated_hours / default
```
Removed value: -null
```
removedOutput schema / properties / estimated_hours / description
```
Removed value: -"Estimate in hours."
```
addedOutput schema / properties / estimated_hours / type
```
Added value: +[
+  "number",
+  "null"
+]
```

removedOutput schema / properties / id / anyOf

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

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

addedOutput schema / properties / id / type

Added value: +[
+  "integer",
+  "string",
+  "null"
+]

removedOutput schema / properties / lock_version / anyOf

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

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

removedOutput schema / properties / lock_version / description

Removed value: -"Optimistic-locking version; pass to update_work_package."

addedOutput schema / properties / lock_version / type
```
Added value: +[
+  "integer",
+  "null"
+]
```
removedOutput schema / properties / notes / default
```
Removed value: -null
```

removedOutput schema / properties / notes / description

Removed value: -"Degradation notes for this result."

changedOutput schema / properties / parent / 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 / parent / default
```
Removed value: -null
```
removedOutput schema / properties / parent / description
```
Removed value: -"Parent work package."
```

removedOutput schema / properties / percentage_done / anyOf

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

removedOutput schema / properties / percentage_done / default
```
Removed value: -null
```
removedOutput schema / properties / percentage_done / description
```
Removed value: -"Progress, 0-100."
```
addedOutput schema / properties / percentage_done / type
```
Added value: +[
+  "integer",
+  "null"
+]
```

changedOutput schema / 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 / priority / default
```
Removed value: -null
```
removedOutput schema / properties / priority / description
```
Removed value: -"Priority."
```

changedOutput schema / 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 / project / default
```
Removed value: -null
```
removedOutput schema / properties / project / description
```
Removed value: -"Owning project."
```

changedOutput schema / properties / project_phase / 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 / project_phase / default
```
Removed value: -null
```

removedOutput schema / properties / project_phase / description

Removed value: -"Project phase this work package sits in (16.1+, only when phases are active in the project and visible to this user); details via get_project_phase."

removedOutput schema / properties / remaining_hours / anyOf

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

removedOutput schema / properties / remaining_hours / default
```
Removed value: -null
```
removedOutput schema / properties / remaining_hours / description
```
Removed value: -"Remaining work in hours."
```
addedOutput schema / properties / remaining_hours / type
```
Added value: +[
+  "number",
+  "null"
+]
```

changedOutput schema / properties / responsible / 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 / responsible / default
```
Removed value: -null
```
removedOutput schema / properties / responsible / description
```
Removed value: -"Accountable user."
```

removedOutput schema / properties / spent_hours / anyOf

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

removedOutput schema / properties / spent_hours / default
```
Removed value: -null
```
removedOutput schema / properties / spent_hours / description
```
Removed value: -"Logged time in hours."
```
addedOutput schema / properties / spent_hours / type
```
Added value: +[
+  "number",
+  "null"
+]
```

changedOutput schema / properties / sprint / 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 / sprint / default
```
Removed value: -null
```

removedOutput schema / properties / sprint / description

Removed value: -"The sprint the work package is planned in; null when unassigned."

removedOutput schema / properties / start_date / anyOf

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

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

changedOutput schema / 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 / status / default
```
Removed value: -null
```
removedOutput schema / properties / status / description
```
Removed value: -"Status."
```

removedOutput schema / properties / story_points / anyOf

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

removedOutput schema / properties / story_points / default
```
Removed value: -null
```
removedOutput schema / properties / story_points / description
```
Removed value: -"Story points."
```
addedOutput schema / properties / story_points / type
```
Added value: +[
+  "integer",
+  "null"
+]
```

removedOutput schema / properties / subject / anyOf

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

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

removedOutput schema / properties / target_versions / description

Removed value: -"All target versions; legacy instances yield zero or one."

removedOutput schema / properties / target_versions / items / description

Removed value: -"A reference to another resource. Canonical output shape."

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

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

removedOutput schema / properties / target_versions / items / properties / id / default
```
Removed value: -null
```
removedOutput schema / properties / target_versions / items / properties / id / description
```
Removed value: -"Resource id."
```
addedOutput schema / properties / target_versions / items / properties / id / type
```
Added value: +[
+  "integer",
+  "string",
+  "null"
+]
```
removedOutput schema / properties / target_versions / items / properties / name / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
removedOutput schema / properties / target_versions / items / properties / name / default
```
Removed value: -null
```
removedOutput schema / properties / target_versions / items / properties / name / description
```
Removed value: -"Human-readable name."
```
addedOutput schema / properties / target_versions / items / properties / name / type
```
Added value: +[
+  "string",
+  "null"
+]
```

changedOutput schema / 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 / type / default
```
Removed value: -null
```
removedOutput schema / properties / type / description
```
Removed value: -"Work package type."
```

removedOutput schema / properties / updated_at / anyOf

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

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

changedOutput schema / properties / version / 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 / version / default
```
Removed value: -null
```

removedOutput schema / properties / version / description

Removed value: -"Legacy alias: the sole target version, or null for zero/multiple."

Changed11 schema fields changedv0.3.3Oct 3, 2026

changedInput schema / properties / assignee / anyOf

Previous value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "type": "integer"
+  },
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

changedInput schema / properties / parent_id / anyOf

Previous value: -[
-  {
-    "type": "integer"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "type": "integer"
+  },
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

changedInput schema / properties / priority / anyOf

Previous value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "type": "integer"
+  },
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

changedInput schema / properties / responsible / anyOf

Previous value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "type": "integer"
+  },
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

addedInput schema / properties / sprint

Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Numeric sprint id; from list_sprints. Omit to leave unset."
+}

changedInput schema / properties / status / anyOf

Previous value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "type": "integer"
+  },
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

addedInput schema / properties / type / anyOf

Added value: +[
+  {
+    "type": "integer"
+  },
+  {
+    "type": "string"
+  }
+]

removedInput schema / properties / type / type
```
Removed value: -"string"
```

changedInput schema / properties / version / anyOf

Previous value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "type": "integer"
+  },
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

changedInput schema / properties / version / description

Previous value: -"Numeric version / sprint id; from get_project_metadata."New value: +"Numeric version id; from get_project_metadata."

addedOutput schema / properties / sprint

Added value: +{
+  "anyOf": [
+    {
+      "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"
+    }
+  ],
+  "default": null,
+  "description": "The sprint the work package is planned in; null when unassigned."
+}

Changed18 schema fields changedv0.3.2Sep 24, 2026

changedInput schema / properties / assignee / description

Previous value: -"Numeric user id to assign. 'me' is not accepted in writes — call get_instance_info for the current user's id."New value: +"Numeric user id ('me' isn't accepted in writes; get_instance_info gives the current user's id)."

changedInput schema / properties / attachment_paths / description

Previous value: -"Local file paths to attach. Files upload uncontainered first and are claimed by the new work package, which is the flow that works even when the author lacks edit permission. Only usable when the server shares a filesystem with you (stdio transport)."New value: +"Local file paths to attach (stdio transport only — the server must share your filesystem)."

changedInput schema / properties / custom_fields / description

Previous value: -"Custom field writes keyed by wire key or display name: {'customField12': 'High'} or {'Severity': 'High'}. List/user/version fields accept option ids or option names. Unknown or ambiguous keys fail with the valid keys listed — nothing is ever silently dropped. get_work_package_schema shows what this project and type accept."New value: +"Custom field writes keyed by wire key or display name: {'customField12': 'High'} or {'Severity': 'High'}. List/user/version fields take ids or names. Unknown keys fail listing the valid ones. get_work_package_schema shows what this project/type accepts."

changedInput schema / properties / date / description

Previous value: -"The single ISO date of a **milestone**. Milestones carry `date` instead of start_date/due_date; passing both shapes is rejected locally."New value: +"ISO date for a **milestone** (used instead of start_date/due_date). Passing both is rejected locally."

changedInput schema / properties / description / description

Previous value: -"Body text in markdown. Omit for an empty description."New value: +"Body text in markdown."

changedInput schema / properties / due_date / description

Previous value: -"ISO date (YYYY-MM-DD). Not valid on milestone types."New value: +"ISO date (YYYY-MM-DD); not valid on milestones."

changedInput schema / properties / estimated_hours / description

Previous value: -"Estimate in hours as a decimal (7.5 = seven and a half)."New value: +"Estimate in hours, decimal (e.g. 7.5)."

changedInput schema / properties / notify / description

Previous value: -"Send OpenProject notification emails for this creation."New value: +"Email notifications for this creation."

changedInput schema / properties / parent_id / description

Previous value: -"Create this as a child of an existing work package id."New value: +"Work package id to create this as a child of."

changedInput schema / properties / priority / description

Previous value: -"Priority name or numeric id ('High', 'Normal', or 8). Omit for the instance default; priority ids differ per instance."New value: +"Priority name or id ('High', 'Normal', or 8). Omit for default."

changedInput schema / properties / project / description

Previous value: -"Numeric project id or project identifier (URL slug). Both come from list_projects."New value: +"Numeric project id or identifier (URL slug); from list_projects."

changedInput schema / properties / remaining_hours / description

Previous value: -"Remaining work in hours as a decimal."New value: +"Remaining work in hours, decimal."

changedInput schema / properties / responsible / description

Previous value: -"Numeric user id of the accountable person."New value: +"Numeric id of the accountable person."

changedInput schema / properties / start_date / description

Previous value: -"ISO date (YYYY-MM-DD). Not valid on milestone types."New value: +"ISO date (YYYY-MM-DD); not valid on milestones."

changedInput schema / properties / status / description

Previous value: -"Status name or numeric id. Omit to take the type's default status — do not guess an id."New value: +"Status name or numeric id. Omit for the type's default; don't guess."

changedInput schema / properties / subject / description

Previous value: -"The title. Required and must not be blank."New value: +"The title; must not be blank."

changedInput schema / properties / target_versions / description

Previous value: -"Target version ids. [] clears assignments; omit to use defaults. Multiple values require instance support. Mutually exclusive with version."New value: +"Target version ids. [] clears; omit to keep defaults. Multiple values need instance support. Mutually exclusive with version."

changedInput schema / properties / type / description

Previous value: -"Work package type as a **name or numeric id** ('Task', 'Bug', 'Milestone', or 7). Names resolve against this instance's types; an unknown or ambiguous name fails with the valid values listed."New value: +"Type name or id ('Task', 'Bug', 'Milestone', or 7). Unknown or ambiguous names fail listing the valid values."

Changed4 schema fields changedv0.3.1Sep 23, 2026

addedInput schema / properties / remaining_hours

Added value: +{
+  "anyOf": [
+    {
+      "minimum": 0,
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Remaining work in hours as a decimal."
+}

addedInput schema / properties / story_points

Added value: +{
+  "anyOf": [
+    {
+      "minimum": 0,
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Story points as a non-negative integer."
+}

addedOutput schema / properties / remaining_hours

Added value: +{
+  "anyOf": [
+    {
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Remaining work in hours."
+}

addedOutput schema / properties / story_points

Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Story points."
+}

Changed3 schema fields changedv0.3.0Sep 14, 2026

addedInput schema / properties / target_versions

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "type": "integer"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Target version ids. [] clears assignments; omit to use defaults. Multiple values require instance support. Mutually exclusive with version."
+}

addedOutput schema / properties / target_versions

Added value: +{
+  "description": "All target versions; legacy instances yield zero or one.",
+  "items": {
+    "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": "array"
+}

changedOutput schema / properties / version / description

Previous value: -"Version / sprint."New value: +"Legacy alias: the sole target version, or null for zero/multiple."

First observedv0.1.0Aug 12, 2026

TDQS

A4.6/5.0

Behavior4/5

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

The annotations already declare the mutating, open-world, non-idempotent profile, and the description goes beyond them by disclosing the form pre-flight: invalid status, missing custom fields and disallowed types come back as structured violations with allowed values 'before anything is written', which tells the agent failures are safe. It also warns that unknown custom-field keys fail with the valid list. The gap is that it never states permission/auth requirements, and the return-value sentence partly duplicates the output schema.

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-loaded with purpose and the pre-flight behavior, then use cases, returns, pitfalls and routing, with a labeled 'Pitfalls' block. Every sentence carries signal except the return-value summary, which restates what the output schema already gives.

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?

For a 21-parameter mutation with an output schema and full annotation coverage, the description supplies what structured data cannot: the validation flow, the name-vs-id convention split, custom-field prerequisites, and the correct sibling to use for updates and attachments. An agent has enough to call this correctly on the first attempt.

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 synthesizes a rule the schema only states per-field: 'type, status and priority take names or ids; versions, assignees and parents need numeric ids.' It also directs the agent to get_work_package_schema for custom fields, which is real added meaning for the riskiest parameter.

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 and resource ('Create a work package') and immediately differentiates the flow from a plain write by noting it is validated through OpenProject's form endpoint first. The covered object kinds (tasks, bugs, subtasks via parent_id, milestones via date) let an agent separate this from update_work_package or create_work_package_relation 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 Guidelines5/5

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

Explicitly names the alternatives and the condition that selects them: 'To change it afterwards use update_work_package; to attach a file to an existing work package use upload_attachment.' It also scopes the creation use cases (subtasks need parent_id, milestones use date) so the agent knows which parameters select which behavior.

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

Deploy Server