redmine-mcp-workflows

redmine_update_issue

Update a Redmine issue's fields and status, with pre-flight checks to block disallowed workflow transitions.

Instructions

Update an issue, with reactive workflow validation on status changes.

Args: issue_id: numeric Redmine issue id. subject: optional new subject. description: optional new description. status: optional id or name (e.g. "In Progress"). Triggers workflow pre-flight against the cache. priority: optional id or name. assigned_to_id: optional user id; 0 means unchanged. notes: optional comment to attach with this update (becomes a journal entry). difficulty: optional engagement-mode level for the global Difficulty custom field. Values: "Unclassified" / "Easy" / "Normal" / "Hard". NO default-fill on update — empty means "don't change Difficulty." held: optional reason string explaining why the issue is held (e.g. "waiting on upstream patch"), which also blocks closing. Empty (default) means unchanged. This is free text a human reads later to decide whether the hold still applies — a bare flag records nothing, so booleans are rejected with held_reason_required. clear_held: set True to remove an existing hold. This is the supported way to un-hold an issue; passing an empty held means "don't change" and cannot clear. Mutually exclusive with a non-empty held. held_until: optional ISO-8601 date ("2026-10-01"). Sets the Held Until custom field. Empty means unchanged. Optional and independent of held — plenty of holds have no knowable end date, so a reason with no date is valid. due_date: optional ISO-8601 date ("2026-05-17"). Empty leaves it unchanged; pass the literal string "" (i.e. just don't send this arg) to leave it untouched. To clear an existing due_date you currently need redmine_request with {"issue": {"due_date": null}} — the MCP can't distinguish "unset" from "leave alone" without explicit null support. start_date: same shape as due_date. done_ratio: optional 0-100 progress percent. -1 (sentinel) means unchanged; 0 is explicit "reset to no progress." fixed_version_id: optional version id (string for id-or-empty). Empty leaves unchanged; explicit "0" clears the version. custom_fields: optional list of {"id": <int>, "value": <str>} entries. Accepts either a Python list (preferred) or a JSON- encoded string. Empty means no custom-field changes.

On a status change the cache pre-flight short-circuits any previously-observed disallowed transition with a :class:WorkflowTransitionDisallowed payload. After a real PUT the outcome is recorded so future calls benefit. Honors REDMINE_MCP_READ_ONLY.

With quiet=True a successful result is reduced to ids + status (bulk: compact per-item rows + summary) instead of the full issue JSON. Errors are never reduced.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`held`	No
`notes`	No
`quiet`	No
`status`	No
`subject`	No
`due_date`	No
`issue_id`	Yes
`priority`	No
`clear_held`	No
`difficulty`	No
`done_ratio`	No
`held_until`	No
`start_date`	No
`description`	No
`custom_fields`	No
`assigned_to_id`	No
`fixed_version_id`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv1.1.0Sep 30, 2026

addedInput schema / properties / clear_held

Added value: +{
+  "default": false,
+  "title": "Clear Held",
+  "type": "boolean"
+}

changedInput schema / properties / held / default
```
Previous value: -falseNew value: +""
```

changedInput schema / properties / held / type

Previous value: -"boolean"New value: +"string"

addedInput schema / properties / quiet

Added value: +{
+  "default": false,
+  "title": "Quiet",
+  "type": "boolean"
+}

First observedv1.0.0Jul 9, 2026

TDQS

A4.5/5.0

Behavior5/5

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

With no annotations, the description carries the full burden and does so richly: it discloses the workflow pre-flight short-circuit and its WorkflowTransitionDisallowed payload, post-PUT outcome caching, the REDMINE_MCP_READ_ONLY flag, held semantics including the held_reason_required rejection of bare booleans, mutual exclusivity of held/clear_held, and quiet-mode output reduction with errors never reduced.

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 one-line purpose followed by a structured Args list, which is an appropriate shape for 17 parameters with no schema-level documentation; nearly every sentence earns its place. It loses a point for the convoluted and self-referential due_date sentence ("pass the literal string \"\" (i.e. just don't send this arg)"), which is harder to parse than it needs to be.

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 17-parameter mutation tool with no annotations and a rich output schema, the description covers purpose, per-parameter edge cases, workflow-validation behavior, environment gating, and the quiet-mode return-shape reduction. Given the output schema already carries return structure, nothing an agent needs to invoke this correctly is missing.

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?

Schema description coverage is 0%, so the description must compensate entirely, and it documents essentially every one of the 17 parameters. It goes well beyond naming them, explaining sentinel semantics (-1 unchanged vs 0 reset for done_ratio; "0" clears fixed_version_id), the explicit-empty-means-unchanged convention, the boolean-rejection on held, and the inability to clear due_date through this tool.

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?

The opening line states a specific verb and resource ("Update an issue") and adds a distinctive behavioral qualifier ("reactive workflow validation on status changes"). It is clearly distinct from read tools, but never explicitly contrasts itself with close cousin siblings such as redmine_bulk_update_issues or redmine_close_issue, leaving the single-vs-bulk boundary to inference.

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?

Strong conditional guidance: status changes trigger a workflow pre-flight, clear_held is named as "the supported way to un-hold," and it explicitly routes the agent to redmine_request for clearing a due_date. It lacks broad when-to-use guidance relative to sibling update tools (bulk vs single, close_issue), so it stops just short of fully explicit routing.

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

Deploy Server