List Task Comments via MCP: Timelines and Audit Trails

Developer reference for the list_task_comments MCP tool. Learn how to retrieve comment history and audit trails for tasks, including pagination and filtering. Includes example tool calls, natural language prompts, edge cases, and troubleshooting.

Tool Overview

Purpose

The list_task_comments tool retrieves the complete comment history for a specific task. Use this tool to review task timelines, understand decision history, read audit trails, or prepare handoff summaries.

Read-only operation: This tool only reads data - it never modifies comments.

Input Parameters

The tool requires a task ID. Pagination parameters are optional.

Output Format

The tool returns a JSON object with comments and pagination information:

{
  "comments": [
    {
      "id": 1,
      "content": "Started working on OAuth integration",
      "author_id": 101,
      "author_name": "John Doe",
      "author_email": "[email protected]",
      "created_at": "2026-02-20T14:22:00Z",
      "updated_at": "2026-02-20T14:22:00Z"
    }
  ],
  "total": 5,
  "limit": 25,
  "offset": 0,
  "has_more": false
}

Response Fields

• comments: Array of comment objects (empty array if no comments)
• total: Total number of comments for this task (across all pages)
• limit: Maximum number of comments returned in this response
• offset: Number of comments skipped (for pagination)
• has_more: Boolean indicating if more comments are available

Comment Object Fields

• id: Unique comment identifier
• content: Comment text content
• author_id: ID of the user who created the comment
• author_name: Name of the comment author
• author_email: Email of the comment author
• created_at: Timestamp when comment was created
• updated_at: Timestamp when comment was last updated

Example Tool Calls

Example 1: List All Comments

Tool Call (JSON):

{
  "tool": "list_task_comments",
  "arguments": {
    "task_id": 123,
    "limit": 50
  }
}

Returns: First 50 comments for task 123

Example 2: Pagination

Tool Call (JSON):

{
  "tool": "list_task_comments",
  "arguments": {
    "task_id": 123,
    "limit": 25,
    "offset": 25
  }
}

Returns: Comments 26-50 (second page)

Natural Language Prompt Examples

Claude Desktop / General AI

User Prompt:

"Show me all comments on task #123"

AI Behavior:

1. AI calls list_task_comments with task_id: 123
2. AI receives comment array
3. AI formats and presents comments chronologically to user

Reviewing Task History

User Prompt:

"What decisions were made on the login feature task?"

AI Behavior:

1. AI finds task using list_tasks with search: "login feature"
2. AI calls list_task_comments with the task ID
3. AI analyzes comments for decision keywords
4. AI presents decision timeline to user

Preparing Handoff

User Prompt:

"Summarize the comment history for task #456 for a handoff"

AI Behavior:

1. AI calls list_task_comments to get all comments
2. AI receives comment timeline
3. AI summarizes key points, decisions, and next steps from comments
4. AI presents handoff summary to user

Common Use Cases

• Task Handoff - Review comment history to prepare handoff summaries
• Progress Updates - Review previous comments before adding new updates
• Task Management - Understand task context and decision history
• Add Comments - Review existing comments before adding new ones

Edge Cases

No Comments

Situation: Task has no comments

Response:

{
  "comments": [],
  "total": 0,
  "limit": 50,
  "offset": 0,
  "has_more": false
}

Handling: This is normal - empty array means task has no comments yet

Task Not Found (404)

Situation: task_id doesn't exist

Response:

{
  "error": "not_found",
  "message": "Task with ID 123 not found"
}

Handling: Verify task ID is correct

Permission Denied (403)

Situation: Task exists but you don't have access to its comments

Response:

{
  "error": "forbidden",
  "message": "You don't have permission to access this task's comments"
}

Handling: Check if you're in the correct workspace or if the task is private

Read 403 troubleshooting guide →

Troubleshooting

Invalid Task ID

Symptom: 400 validation error or 404 not found

Causes:

• Task ID is not a number
• Task ID doesn't exist
• Task was deleted

Fix:

• Verify task ID is a valid integer
• Use list_tasks or get_task to find valid IDs
• Check if task still exists in Corcava

Access Denied (403)

Symptom: 403 Forbidden error

Causes:

• Task belongs to a different workspace
• Task is private and you're not assigned
• API key doesn't have access to the workspace

Fix:

• Verify you're accessing the correct workspace
• Check task permissions in Corcava
• Verify API key has access to the workspace

Read 403 troubleshooting guide →

Best Practices

Using list_task_comments Effectively

• ✅ Use pagination (limit/offset) for tasks with many comments
• ✅ Review comments before adding new ones to avoid duplicates
• ✅ Use comments to understand task context and decision history
• ✅ Combine with get_task for complete task context
• ✅ Sort comments chronologically (they're returned in creation order)

Related Tools

Often used together with:

• get_task - Get task details (includes recent comments)
• add_task_comment - Add new comments to tasks
• list_tasks - Find task IDs before listing comments