Add a Task Comment via MCP: Updates, Decisions, and Next Steps

Developer reference for the add_task_comment MCP tool. Learn how to add comments to tasks for progress updates, decisions, and next steps. Includes safety checks, confirmation patterns, example tool calls, natural language prompts, edge cases, and troubleshooting.

Tool Overview

Purpose

The add_task_comment tool adds a new comment to a task. Use this tool to log progress updates, document decisions, record next steps, or provide context for future reference.

⚠️ Write operation: This tool modifies data - always use confirmation patterns before calling it.

Input Parameters

Both task_id and content are required.

Output Format

The tool returns the newly created comment object:

{
  "id": 5,
  "content": "Completed OAuth integration",
  "author_id": 101,
  "author_name": "John Doe",
  "author_email": "[email protected]",
  "created_at": "2026-03-18T10:30:00Z",
  "updated_at": "2026-03-18T10:30:00Z",
  "task_id": 123
}

Safety Checks and Confirmation Patterns

⚠️ Always Confirm Before Adding Comments

Never let AI add comments without explicit confirmation. Use these patterns:

• Preview First: Show what comment will be added before executing
• Confirmation Token: Require "CONFIRM" before calling add_task_comment
• Review Content: Display comment text for review before posting
• Verify Task: Confirm task ID and title before adding comment

Learn more about safe write workflows →

Safe Prompt Pattern

✅ Safe Prompt Template:

"I want to add a comment to task #123: [comment text]. 
Show me exactly what you'll post (task title and comment text) 
and wait for me to type CONFIRM before adding it. 
If I don't type CONFIRM, don't add anything."

Example Tool Calls

Example 1: Add Progress Update

Tool Call (JSON):

{
  "tool": "add_task_comment",
  "arguments": {
    "task_id": 123,
    "content": "Completed OAuth integration. Ready for review."
  }
}

Returns: Created comment object with all fields

Example 2: Add Decision Record

Tool Call (JSON):

{
  "tool": "add_task_comment",
  "arguments": {
    "task_id": 456,
    "content": "Decision: Using OAuth 2.0 instead of OAuth 1.0 for better security and modern standards."
  }
}

Returns: Created comment object documenting the decision

Natural Language Prompt Examples

Safe Comment Addition with Confirmation

User Prompt:

"Add a comment to task #123 saying 'OAuth integration is complete'. Show me what you'll post first, then wait for CONFIRM."

AI Behavior:

1. AI calls get_task to verify task exists and get title
2. AI shows preview: "Task: Login Feature, Comment: OAuth integration is complete"
3. AI waits for "CONFIRM"
4. AI calls add_task_comment only after confirmation
5. AI confirms comment was added

Progress Update Workflow

User Prompt:

"I finished the login feature. Add a progress update comment to task #123, but show me the comment first."

AI Behavior:

1. AI drafts comment: "Progress update: Login feature implementation completed"
2. AI shows preview and asks for confirmation
3. User approves
4. AI calls add_task_comment

Common Use Cases

• Progress Updates - Log regular progress updates on tasks
• Task Handoff - Add handoff comments with context and next steps
• Standup Summary - Post standup summaries as task comments
• Review Comments - Review existing comments before adding new ones

Edge Cases

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

Empty Content

Situation: content is empty or whitespace only

Response:

{
  "error": "validation_error",
  "message": "Content cannot be empty",
  "field": "content"
}

Handling: Ensure content has non-whitespace text

Permission Denied (403)

Situation: Task exists but you don't have permission to comment

Response:

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

Handling: Check task permissions in Corcava

Read 403 troubleshooting guide →

Troubleshooting

Validation Errors (400)

Symptom: 400 Bad Request with validation error

Causes:

• Missing required field (task_id or content)
• Empty content (whitespace only)
• Invalid task_id format

Fix:

• Ensure both task_id and content are provided
• Verify content has actual text (not just spaces)
• Verify task_id is a valid integer

Read validation troubleshooting →

Task Not Found (404)

Symptom: 404 Not Found error

Causes:

• Task ID doesn't exist
• Task was deleted
• Invalid task_id format

Fix:

• Verify task_id is correct
• Use list_tasks or get_task to find valid IDs
• Check if task still exists

Best Practices

Using add_task_comment Safely

• ✅ Always preview comment content before posting
• ✅ Require explicit confirmation (CONFIRM token)
• ✅ Verify task ID and title before adding comment
• ✅ Review existing comments to avoid duplicates
• ✅ Use clear, actionable comment text
• ✅ Include context and next steps when appropriate

Related Tools

Often used together with:

• list_task_comments - Review existing comments before adding new ones
• get_task - Verify task exists before commenting
• Least-Privilege Workflows - Safe write workflow patterns