Update a Task via MCP: Patch Patterns, Status Changes, and Validation

Developer reference for the update_task MCP tool. Learn how to update task fields using patch patterns, handle status transitions, validate changes, and use confirmation patterns. Includes example tool calls, natural language prompts, edge cases, and troubleshooting.

Tool Overview

Purpose

The update_task tool updates one or more fields of an existing task. Use this tool to change status, update priorities, modify due dates, or update any other task field.

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

Input Parameters

The tool uses a patch pattern - only include fields you want to update. All fields are optional except task_id.

Patch Patterns

The update operation uses a patch pattern - you only send the fields you want to change. Fields not included in the request remain unchanged.

Partial Updates:

• Single field: {"task_id": 123, "status": "done"} - Only updates status
• Multiple fields: {"task_id": 123, "status": "in_progress", "priority": "high"} - Updates both
• Clear field: {"task_id": 123, "due_date": null} - Removes due date

Status Transitions

Tasks can transition between statuses. Common workflows:

Valid Status Values:

• "open" - Task is created but not started
• "in_progress" - Task is actively being worked on
• "done" - Task is completed
• "blocked" - Task cannot proceed due to dependencies or issues

Common Status Workflows:

Starting Work: open → in_progress

{
  "tool": "update_task",
  "arguments": {
    "task_id": 123,
    "status": "in_progress"
  }
}

Completing Task: in_progress → done

{
  "tool": "update_task",
  "arguments": {
    "task_id": 123,
    "status": "done"
  }
}

Blocking Task: Any status → blocked

{
  "tool": "update_task",
  "arguments": {
    "task_id": 123,
    "status": "blocked"
  }
}

Output Format

The tool returns the updated task object with all fields (including unchanged ones):

{
  "id": 123,
  "title": "Implement login feature",
  "description": "Add user authentication...",
  "status": "in_progress",
  "priority": "high",
  "due_date": "2026-02-28",
  "project_id": 456,
  "board_id": 789,
  "assignee_id": 101,
  "updated_at": "2026-03-05T14:30:00Z"
}

Safety Checks and Confirmation Patterns

⚠️ Always Preview Changes Before Updating

Never let AI update tasks without showing what will change. Use these patterns:

• Read First: Call get_task to read current state
• Show Diff: Display "Current: X → New: Y" for each field
• Confirmation Token: Require "CONFIRM" before calling update_task

Learn more about safe write workflows →

Safe Prompt Pattern

✅ Safe Prompt Template:

"I want to update the [task name] task: [changes]. 
First, show me the current task details, then show me what will change. 
Only update if I type CONFIRM. 
If I don't confirm, don't make any changes."

Example Tool Calls

Example 1: Update Status Only

Tool Call (JSON):

{
  "tool": "update_task",
  "arguments": {
    "task_id": 123,
    "status": "done"
  }
}

Returns: Task with status updated to "done", all other fields unchanged

Example 2: Update Multiple Fields

Tool Call (JSON):

{
  "tool": "update_task",
  "arguments": {
    "task_id": 123,
    "status": "in_progress",
    "priority": "high",
    "due_date": "2026-03-10"
  }
}

Returns: Task with status, priority, and due_date updated

Example 3: Clear Due Date

Tool Call (JSON):

{
  "tool": "update_task",
  "arguments": {
    "task_id": 123,
    "due_date": null
  }
}

Returns: Task with due_date removed (set to null)

Natural Language Prompt Examples

Safe Update with Diff Preview

User Prompt:

"Update the login feature task status to done. First show me the current task, then show what will change, then wait for CONFIRM."

AI Behavior:

1. AI calls get_task to read current state
2. AI shows: "Current: Status = In Progress, New: Status = Done"
3. AI waits for "CONFIRM"
4. AI calls update_task only after confirmation
5. AI confirms task was updated

Batch Status Update

User Prompt:

"Mark all tasks in the Q1 project as done. Show me the list first, then wait for CONFIRM ALL."

AI Behavior:

1. AI calls list_tasks filtered by project
2. AI shows list of tasks that will be updated
3. AI waits for "CONFIRM ALL"
4. AI calls update_task for each task

Common Use Cases

• Progress Updates - Update task status and add progress comments
• Batch Title Cleanup - Standardize task titles across multiple tasks
• Task Management - Update priorities, due dates, and assignments

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

Invalid Status Transition

Situation: Status value is invalid

Response:

{
  "error": "validation_error",
  "message": "Invalid status. Must be: open, in_progress, done, or blocked",
  "field": "status"
}

Handling: Use only valid status values

Read-Only Fields

Situation: Attempting to update fields that can't be changed (e.g., id, created_at)

Response: These fields are ignored (no error, but no change)

Handling: Only include updatable fields in the patch

No Changes

Situation: Update request doesn't change any fields (all values same as current)

Response: Task object returned unchanged (no error)

Handling: This is valid - tool returns current state

Troubleshooting

Validation Errors (400)

Symptom: 400 Bad Request with validation error

Causes:

• Invalid status or priority value
• Invalid date format for due_date
• Invalid project_id or board_id
• Invalid assignee_id

Fix:

• Verify all field values are valid
• Use ISO date format (YYYY-MM-DD)
• Verify IDs exist before using them

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 update_task Safely

• ✅ Always call get_task first to read current state
• ✅ Show diff preview before updating (Current → New)
• ✅ Require explicit confirmation (CONFIRM token)
• ✅ Use patch pattern - only include fields to update
• ✅ Verify task_id is correct before updating
• ✅ Validate status transitions make sense
• ✅ Add audit comments explaining why changes were made
• ✅ Handle batch updates carefully (show full list first)

Related Tools

Often used together with:

• get_task - Read current task state before updating
• list_tasks - Find tasks to update
• Least-Privilege Workflows - Safe write workflow patterns