Skip to main content
Glama

update_task

Updates a task's status, owner, or validation notes on the shared blackboard so you can claim work, hand off responsibility, or mark tasks completed with verification proof.

Instructions

Updates the status, owner, or validation notes of a task in the Tier 3 Task Graph.

Call this tool to claim work, hand off responsibility to another agent, or mark work as completed with proof of verification.

Status Conventions:

  • 'pending': Queued task waiting to be started.

  • 'in_progress': Currently being worked on. MUST have an 'assigned_to' owner to avoid triggering '⚠️ Attention Required' health warnings.

  • 'completed': Finished work. MUST include validation notes (e.g., test results, verification commands) for audit trail compliance.

Args: task_id: Unique task identifier (e.g., 'task-04', 'FEAT-BLACKBOARD'). status: Target status ('pending', 'in_progress', 'completed'). title: Optional updated title if creating or renaming the task. assigned_to: Agent or user claiming the baton (e.g., 'claude', 'antigravity', 'human'). notes: Progress updates or verification proof (e.g., '46/46 tests passed in 0.41s').

Returns: str: Confirmation message reflecting the updated task state.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "task_id": "<task_id>",
      "status": "<status>"
    },
    "name": "update_task"
  }
}

Input Schema

NameRequiredDescriptionDefault
notesNo
titleNo
statusYes
task_idYes
assigned_toNo

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.1

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations present, the description carries the full burden and does well: it discloses the state machine (pending/in_progress/completed), the hard requirement that in_progress carry an assigned_to or trigger '⚠️ Attention Required' warnings, and that completed requires validation notes for audit compliance. It omits any mention of permissions, invalid transitions, or error behavior for unknown task_id, which keeps it below a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded purpose sentence followed by scenario guidance, status conventions, and args - a clean hierarchy. The docstring-style Args/Returns blocks are slightly redundant given a structured schema and output schema exist, but nothing is padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Rich enough for a 5-parameter mutation tool: it explains state requirements, per-parameter meaning, and confirms a string confirmation is returned. Missing only edge-case behavior such as unknown task_id, rejected status transitions, or whether omitted fields are cleared.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate entirely, and it does: all five parameters are documented with semantics plus concrete examples ('task-04', 'FEAT-BLACKBOARD', 'claude', '46/46 tests passed in 0.41s'). It also supplies the valid status values that the schema leaves as an unconstrained string.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Updates the status, owner, or validation notes of a task in the Tier 3 Task Graph") and immediately enumerates the three supported operations. No sibling in the supplied list does task mutation, so no disambiguation is needed.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use guidance tied to three concrete scenarios: claiming work, handing off responsibility, and marking work completed. It does not state any when-not conditions or what to do if a task is already completed, but the positive guidance is strong and actionable.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.