ProTask MCP server has moderate definition quality with significant gaps across multiple dimensions. Strengths: all 39 tools have names following verb_noun conventions, descriptions are present (averaging ~80-120 chars), and input schemas are visible with types defined. Critical weaknesses: (1) Parameter descriptions are sparse or missing context. For example, 'protask_create_task' has 'due_date' described only as 'Due date (YYYY-MM-DD format)' with no guidance on whether past dates are allowed or required. (2) Output schemas are completely undocumented, no tool response structure is defined, forcing LLMs to guess what fields to expect. This breaks downstream tool chaining. (3) No error handling guidance, tools fail silently with no recovery hints. (4) No tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite having destructive operations like delete_project and delete_task. (5) Parameter relationships not documented, e.g., protask_create_task requires both list_id and project_id, but it's unclear if they must match or if list_id alone would suffice. (6) Several tools accept numeric IDs only (project_id, user_id, workspace_id), forcing extra lookup calls when users naturally reference names or emails. Average per-tool score: 42/100.
No output schemas documented. LLMs cannot infer response structure, breaking downstream tool chaining and forcing extra lookup calls. For example, after calling protask_create_task, the LLM does not know if the response includes task_id, and if so, what the field is named.
Tool annotations missing. No readOnlyHint, destructiveHint, or idempotentHint on any tool, despite having destructive operations (delete_project, delete_task, delete_board_list) that need clear marking. LLMs cannot distinguish safe reads from dangerous writes.
Add output schemas to all tools. Document response fields with types and descriptions. For create_* operations, always return the created resource ID and key fields needed for downstream calls (e.g., task_id, task_title after create_task). Reference pattern:tool-response-schema.
Add tool annotations to all tools. Mark read-only tools with readOnlyHint=true, destructive tools (delete_*) with destructiveHint=true, and idempotent tools with idempotentHint=true. This enables LLMs to reason about safety and retry logic.
Extend parameters to accept human-readable identifiers. Add alternate parameters like project_name, user_email, workspace_name alongside numeric IDs. Implement name-to-ID resolution inside tools. This reduces lookup call chains and matches how users naturally speak. Reference pattern:natural-identifiers.
Enhance parameter descriptions with validation rules and examples. For due_date, specify: 'ISO 8601 date (YYYY-MM-DD). Future or present dates only; past dates rejected.' For color, add: 'Hex code 6-char format (e.g., #FF5733). Invalid format returns 422 error.' For list_id in create_task, add: 'Board list ID must belong to the specified project_id.'
Document parameter relationships explicitly. For protask_create_task, state: 'list_id and project_id: the list must belong to the project; providing mismatched IDs returns a 400 error.' For protask_add_checklist_item, state: 'checklist_id must belong to the task specified in task_id.'
Add error recovery hints to tool descriptions and implement structured error responses. When protask_get_task(999) fails, return: {error: 'not_found', message: 'Task 999 not found', suggestion: 'Try list_tasks to find existing task IDs'}. Enable LLMs to self-correct without fallback calls.
ID-only parameter design forces extra lookup calls. All tools accept only numeric IDs (workspace_id, project_id, user_id, task_id) with no human-readable alternatives. Users naturally say 'Add John to the task' or 'Create a task in Q4 Planning', but agents must call lookup tools first to get IDs. See pattern:natural-identifiers.
Parameter descriptions lack actionable constraints. For example, 'due_date' is documented as 'Due date (YYYY-MM-DD format)' but does not specify: Can past dates be set? Is the field optional or required? Does the system auto-adjust invalid dates? LLMs guess and make mistakes.
No error recovery guidance. Tools fail with no actionable error messages. When protask_get_task returns a 404 or protask_create_task fails due to invalid list_id, the LLM has no hint on what to try next. See pattern:recovery-guide.
Undocumented parameter relationships. protask_create_task requires both project_id and list_id, but the description does not clarify: Must the list belong to the project? What if they conflict? Similar issue in protask_add_checklist_item (task_id, checklist_id, item_id), is the checklist_id scoped to the task?
No pagination guidance. protask_list_tasks, protask_list_projects, protask_list_users, and protask_list_comments do not document if results are paginated, what the default limit is, or how to fetch more results. Large result sets could exhaust the LLM context window.
Generic descriptions for complex operations. 'Update a task' and 'Update a project' are vague, do they replace all fields or merge? Can you update title without touching description? LLM must guess, risking unintended overwrites.
Document pagination behavior. For list_* tools, specify: 'Returns up to 50 results per call. Include page=2 to fetch the next batch. Returns total_count and next_cursor if more results exist.' Add limit and offset/cursor parameters and document their ranges.
Clarify merge vs. replace semantics in update_* tools. Specify: 'update_task merges provided fields; omitted fields retain their current values. To clear a field, pass null. Example: {task_id: 42, title: 'New Title'} updates only title; description stays unchanged.'
Add confirmation support for destructive operations. Implement a dry-run or confirm_delete pattern for delete_project, delete_task, delete_board_list. Example: Call delete_project(project_id=1, dry_run=true) to preview impact; omit dry_run or set to false to execute. Returns: 'Deleting project 1 would delete 3 sub-projects and 42 tasks. Confirm: delete_project(1, dry_run=false).'
Add missing optional parameters for common use cases. For create_task, add optional parameters like assigned_user_id, labels (array), and priority so agents can create fully-formed tasks in one call rather than create then update. For create_comment, support optional attachments or mentions.
Document timeout and rate limits. Specify: 'API calls timeout after 30 seconds. Retry with exponential backoff; max 3 retries. Rate limit: 100 requests per minute per user.' Include guidance in tool descriptions.