The OpenProject MCP server provides 7 tools with explicit schemas and descriptions, but suffers from significant gaps in parameter documentation, output schema clarity, and error handling guidance. Tool names follow verb_noun convention appropriately (get_, update_, list_, create_). However, 5 of 7 tools lack descriptions for critical parameters, and no tool documents its output schema structure. Error handling is absent, tools raise generic HTTPException without recovery guidance. The server lacks enum constraints for categorical parameters (status, priority, work_package_type), forcing LLMs to guess valid values. Parameter descriptions are present but often generic (e.g., 'The work package identifier' for wp_id lacks format/length guidance). Security is reasonable (API key injected via environment, no secrets in params), but no permission gates or audit logging. Composition is clean, tools are single-purpose and chainable (get_project_details, update_project; list_work_packages, get_work_package_details). Overall, the server is functional but below production quality for agent reliability.

• Document output schema for every tool. Example for get_work_package_details: 'Returns {id: string, lockVersion: integer, subject: string, description: string, status: string, priority: string, type: string}.'
• Add enum constraints to categorical parameters. Example: status in update_work_package: enum: ['new', 'in_progress', 'closed', 'on_hold'].
• Add pagination to list_* tools. Add parameters: limit (default 20, max 100), offset (default 0). Document: 'Returns up to 20 items. Use offset for pagination.'
• Enhance error handling. Return structured errors with actionable guidance. Example: 'Invalid status: got "pending", must be one of: new, in_progress, closed. See list_work_packages to verify available statuses.'
• Document optimistic locking pattern. For update_work_package/update_project: 'lock_version is required for concurrent edit detection. Obtain via get_work_package_details. If update fails with lock mismatch, call get_work_package_details to refresh and retry.'
• Add format/range documentation to parameters. Example wp_id: 'Numeric work package ID (e.g., 42) or alias.'
• Document default values as fallbacks, not constraints. Example: work_package_type default 'Task' is reasonable, but also list valid types in description.
• Add per-tool recovery hints. Example for list_projects with parent_id: 'If parent_id is not found, call list_projects with no parent_id to discover available root projects.'
• Implement idempotency guidance. For create_work_package, clarify: 'Creating the same work package twice produces two records. If retrying after timeout, verify via list_work_packages before retrying.'

Inferred effective spec: <=2025-11-25.

• Relies on Logging (deprecated) - log to stderr or use OpenTelemetry