redmine-mcp-workflows

redmine_create_issue

Create Redmine issues with validated project, tracker, subject, priority, and custom fields via cache-aware ID resolution, avoiding workflow validation errors.

Instructions

Create an issue with cache-aware id resolution.

Args: project: numeric id or identifier slug (e.g. "claudecode"). tracker: numeric id or name (e.g. "Bug"). subject: required, must be non-empty. description: optional issue body. priority: optional id or name (e.g. "High"); defaults to tracker default when empty. status: optional id or name. Most fleets force initial status via workflow; this is rarely needed. assigned_to_id: optional Redmine user id; 0 means unassigned. difficulty: optional engagement-mode level for the global Difficulty custom field. Values: "Unclassified" / "Easy" / "Normal" / "Hard". When omitted, the field default-fills with "Unclassified" so auto-callers don't trip the required-field validation. Silently no-ops on fleets that don't have a Difficulty field configured. held: optional reason string explaining why the issue is held (e.g. "waiting on upstream patch"). A held issue cannot be closed. Empty (default) leaves the Held field unset. This is free text a human reads later to decide whether the hold still applies, so a bare flag is not accepted. held_until: optional ISO-8601 date ("2026-10-01"). Sets the Held Until custom field. Optional and independent of held — many holds have no knowable end date ("until upstream ships a fix"), so a reason with no date is a normal, valid state. Empty leaves it unset. due_date: optional ISO-8601 date ("2026-05-17"). Empty leaves it unset. start_date: optional ISO-8601 date. Empty leaves it unset (Redmine defaults to the creation date). done_ratio: optional 0-100 progress percent. -1 (sentinel) means unset; 0 is explicit "no progress yet." custom_fields: optional list of {"id": <int>, "value": <str>} entries for arbitrary custom fields. Accepts either a Python list (preferred — Claude can pass it natively) or a JSON- encoded string. Empty string means no custom-field changes beyond what difficulty sets.

Returns the created issue or a structured validation error. 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
`quiet`	No
`status`	No
`project`	Yes
`subject`	Yes
`tracker`	Yes
`due_date`	No
`priority`	No
`difficulty`	No
`done_ratio`	No
`held_until`	No
`start_date`	No
`description`	No
`custom_fields`	No
`assigned_to_id`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv1.1.0Sep 30, 2026
- 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.1/5.0

Behavior4/5

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

With no annotations, the description carries the behavioral burden and mostly delivers: it discloses REDMINE_MCP_READ_ONLY honoring, that held issues cannot be closed, that difficulty silently no-ops on fleets lacking the field, and that quiet reduces success output while errors are never reduced. It omits auth/permission requirements, which would complete the picture for a write tool.

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?

The description is long but front-loaded and organized as an Args block, with each entry earning its place given the 15 undocumented parameters. The one structural flaw is that quiet is explained in a trailing paragraph rather than in the Args list, breaking the established pattern.

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 15-parameter mutation tool at 0% schema coverage, the description is unusually complete: every parameter is addressed, mutation side effects (read-only mode, held-cannot-close) are disclosed, and failure behavior ('structured validation error', errors never reduced) is stated. Since an output schema exists, return values need not be re-described.

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 carry all parameter meaning, and it does: sentinel semantics (done_ratio -1 vs 0, assigned_to_id 0 = unassigned), format examples (ISO-8601 dates, id-or-slug for project/tracker), the constraint that held must be a reason string not a bare flag, the independence of held vs held_until, and custom_fields' dual list-or-JSON-string acceptance.

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+resource ('Create an issue') plus the distinguishing mechanism ('cache-aware id resolution'), which cleanly separates it from redmine_update_issue, redmine_get_issue, and redmine_bulk_create_issues. It does not, however, explicitly name the bulk sibling or spell out the boundary, so sibling routing is left implicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

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

There are scattered usage hints ('status... is rarely needed', 'difficulty... so auto-callers don't trip the required-field validation'), which help an agent decide which optional params to populate. But there is no explicit when-to-use-this-vs-alternatives guidance (e.g., versus redmine_bulk_create_issues) and no stated prerequisites other than the read-only env var.

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

Deploy Server