TaskUpdate

A built-in definition supplied to the request when the tools option was omitted.

Captured description

Use this tool to update a task in the task list.

When to Use This Tool

Mark tasks as resolved:

  • When you have completed the work described in a task

  • When a task is no longer needed or has been superseded

  • IMPORTANT: Always mark your assigned tasks as resolved when you finish them

  • After resolving, call TaskList to find your next task

  • ONLY mark a task as completed when you have FULLY accomplished it

  • If you encounter errors, blockers, or cannot finish, keep the task as in_progress

  • When blocked, create a new task describing what needs to be resolved

  • Never mark a task as completed if:

    • Tests are failing
    • Implementation is partial
    • You encountered unresolved errors
    • You couldn’t find necessary files or dependencies

Delete tasks:

  • When a task is no longer relevant or was created in error
  • Setting status to deleted permanently removes the task

Update task details:

  • When requirements change or become clearer
  • When establishing dependencies between tasks

Fields You Can Update

  • status: The task status (see Status Workflow below)
  • subject: Change the task title (imperative form, e.g., “Run tests”)
  • description: Change the task description
  • activeForm: Present continuous form shown in spinner when in_progress (e.g., “Running tests”)
  • owner: Change the task owner (agent name)
  • metadata: Merge metadata keys into the task (set a key to null to delete it)
  • addBlocks: Mark tasks that cannot start until this one completes
  • addBlockedBy: Mark tasks that must complete before this one can start

Status Workflow

Status progresses: pending → in_progress → completed

Use deleted to permanently remove a task.

Staleness

Make sure to read a task’s latest state using TaskGet before updating it.

Examples

Mark task as in progress when starting work:

{"taskId": "1", "status": "in_progress"}

Mark task as completed after finishing work:

{"taskId": "1", "status": "completed"}

Delete a task:

{"taskId": "1", "status": "deleted"}

Claim a task by setting owner:

{"taskId": "1", "owner": "my-name"}

Set up task dependencies:

{"taskId": "2", "addBlockedBy": ["1"]}

Input schema

JSON 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "taskId": {
      "description": "The ID of the task to update",
      "type": "string"
    },
    "subject": {
      "description": "New subject for the task",
      "type": "string"
    },
    "description": {
      "description": "New description for the task",
      "type": "string"
    },
    "activeForm": {
      "description": "Present continuous form shown in spinner when in_progress (e.g., \"Running tests\")",
      "type": "string"
    },
    "status": {
      "description": "New status for the task",
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "pending",
            "in_progress",
            "completed"
          ]
        },
        {
          "type": "string",
          "const": "deleted"
        }
      ]
    },
    "addBlocks": {
      "description": "Task IDs that this task blocks",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "addBlockedBy": {
      "description": "Task IDs that block this task",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "owner": {
      "description": "New owner for the task",
      "type": "string"
    },
    "metadata": {
      "description": "Metadata keys to merge into the task. Set a key to null to delete it.",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    }
  },
  "required": [
    "taskId"
  ],
  "additionalProperties": false
}

Independent estimate

~1,375 tokens

The captured tool object was counted against the common baseline. This value supports comparison and is not additive.