This MCP server exposes 20 project management tools with moderate structural coverage but significant quality gaps. Schemas are present for all tools with proper JSON Schema type definitions and enums. However, parameter descriptions are almost entirely missing (none visible in the code sample), which is a critical issue for LLM tool selection. Tool descriptions are brief but present. The server lacks error handling guidance, output schema documentation, and proper composition patterns. Many tools appear to duplicate functionality without clear differentiation (e.g., multiple project lookup methods). No tool annotations (readOnlyHint, destructiveHint) are present despite clear semantic distinctions between read and write operations.
Parameter descriptions are missing or minimal across all 20 tools. Parameters like 'active_only', 'limit', 'git_remote_url', 'status', 'worker_type', 'worker_name' have no descriptions visible in schema definitions. LLMs cannot infer parameter semantics from names alone (e.g., is 'status' a filter or a workflow state?).
No output schema documentation visible for any tool. LLMs cannot plan downstream tool calls or extract required chaining IDs (e.g., after list_projects, what fields are returned? Can the result be directly passed to create_task?). This breaks tool composition.
Add comprehensive parameter descriptions for all 20 tools. For each param, specify: (1) what it controls, (2) expected format/type, (3) valid range/enum values, (4) defaults and when they apply. Example: 'limit: Maximum number of projects to return (1-100, default 20). For large result sets, paginate using the returned next_cursor.'
Document output schemas for all tools. For each tool, specify the response object structure, required fields, and chaining-relevant IDs. Example for list_projects: 'Returns {projects: [{id, name, description, git_remote_url, created_at}], total_count, next_cursor}'.
Add tool annotations to clarify semantics. Use readOnlyHint=true for list_*, get_*, search_* tools. Use destructiveHint=true for delete, update-to-abandoned, and irreversible state changes. Use idempotentHint=true for upsert_comment and other idempotent operations.
Consolidate project lookup methods. Merge get_project and get_project_by_git_remote into a single tool accepting either project_id or git_remote_url (as mutually exclusive parameters with clear descriptions). Reduce LLM disambiguation overhead.
Expand tool descriptions from current ~40 chars to 100-150 chars with actionable guidance. Example: 'List all projects, optionally filtered by active status or git remote URL. Use this to discover available projects before creating tasks. Returns paginated results; pass next_cursor to fetch subsequent pages.'
Implement error recovery guidance in tool descriptions and implementation. For each tool, document failure modes (auth, not found, validation, timeout) and suggest next steps. Example: 'If project_id not found, call list_projects to verify ID. If timeout occurs, the backend may be restarting, retry after 5 seconds.'
Multiple tools query the same resource (projects) via different methods without clear guidance on when to use each. 'get_project' (by ID), 'get_project_by_git_remote' (by URL), and implicit filtering in 'list_projects' create composition ambiguity. LLM may waste cycles deciding between them.
No error handling guidance. The callRPC method includes timeout and Cloudflare error detection in code, but tools do not document what errors they return, when to retry, or what the LLM should do on failure. Generic error messages like 'Invalid input' provide no actionable recovery path.
Pagination not consistently implemented or documented. 'list_projects' and 'list_tasks' accept 'limit' but descriptions don't specify whether a 'next_cursor' or 'offset' is returned. Large result sets risk context window exhaustion.
No confirmation or dry-run pattern for irreversible operations. 'delete' or cascading 'update' operations (e.g., update_task to 'abandoned' status) have no protective confirmation step. Agents can accidentally destroy data without user confirmation.
Tool descriptions are generic and lack actionable guidance. E.g., 'Create new project' does not explain when to use create_project vs get_project, whether it's idempotent, or what dependencies exist. Descriptions under 40 chars do not meet LLM optimization baselines (50-200 chars typical for A-grade tools).
'get_recent_activity' accepts no parameters and returns unspecified output. No description of filtering, time range, or structure. Tool appears incomplete or not well-defined.
get_recent_activity
Add explicit pagination documentation. All list_* and search_* tools should return (results, total_count, next_cursor/offset). Specify default and max limits (e.g., limit 1-100, default 20). Document how to handle large result sets.
Implement confirmation pattern for write operations. For irreversible changes (delete status, cascading updates), add optional 'confirm: true' parameter. If omitted or false, return a preview of changes and ask user to call again with confirm=true. Prevents accidental data loss.
Clarify the get_recent_activity tool. Add parameters (project_id?, time_range?, limit?), specify what activity types are included, and document the output structure. Currently appears incomplete.
Validate inputs early with actionable error messages. When an LLM passes invalid status enum ('in-progress' instead of 'in_progress'), return: 'Invalid status: got "in-progress", must be one of: [todo, in_progress, ready_for_review, under_review, done, blocked, abandoned]'. Enables LLM self-correction.
Add batch operation support. For tools like upsert_comment that might be called in loops, offer array variants (e.g., upsert_comments accepting array of comment objects) to reduce token overhead and latency.
Document response field naming consistency. Ensure tool A's output IDs (e.g., project_id) match parameter names in tool B (e.g., project_id in create_task). Current code does not show response structures, so verify this.
Reduce required parameters by providing smart defaults. For example, create_task could default status='todo', priority='medium', worker_type=null (unassigned) so simple invocations don't require every param.