Skip to main content
Glama

update_task

Update a task. Pass only the fields to change. Use this to mark a task done (status: 'done') or move it between epics. Descriptions are summaries. If the task has a detailed spec, create a document and link it with documentId. Work only on items assigned to the user unless told otherwise; see list_tasks assignee='me'. When setting status to 'blocked', include a blockedReason. Don't invent priority — leave it unset if unknown.

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": {
      "taskId": "<taskId>"
    },
    "name": "update_task"
  }
}

Input Schema

NameRequiredDescriptionDefault
sizeNo
typeNo
titleNo
epicIdNoMove to this epic, or null to make standalone
labelsNoReplaces the full label set. Free-form tags, e.g. ['ui', 'auth']
statusNo
taskIdYes
assigneeNo"me", a person's name, the email shown for members without a name, or id, or null to unassign (inherits from the epic owner).
priorityNo
surfacesNoSurface names or ids this task concerns. Replaces the full set; [] = inherit the epic's surfaces.
documentIdNoLink a detail/spec document. Pass null to unlink.
descriptionNo
blockedReasonNoWhy the task is blocked. Only used when status is 'blocked'.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / surfaces
      Added value: +{
      +  "description": "Surface names or ids this task concerns. Replaces the full set; [] = inherit the epic's surfaces.",
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
  2. First observed

TDQS

A3.8/5.0
Behavior4/5

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

With no annotations, the description carries the full burden and does substantial work: it declares partial-update behavior, a cross-field constraint (blockedReason required when status='blocked'), a workflow convention (detail goes in a linked document via documentId), and an anti-hallucination rule for priority. It stops short of covering permissions, invalid taskId behavior, or whether state transitions are constrained.

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?

The lead sentence front-loads purpose and the core invocation rule, and each following clause carries a distinct constraint rather than repeating the schema. The semicolon-chained rule sentences are dense but every one earns its place.

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

Completeness3/5

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

For a 13-parameter mutation tool with zero annotations, no output schema, and sub-50% schema coverage, the description covers the highest-risk behaviors but leaves several fields and all failure modes undocumented. Adequate to call the tool, incomplete for calling it confidently across all parameters.

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

Parameters3/5

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

Schema description coverage is 46%, below the majority threshold, so the description must compensate and only partially does. It adds real meaning for status/blockedReason, documentId, and priority, but title, type, size, and description have no schema documentation and no clarifying text here either.

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

Purpose4/5

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

The description opens with a specific verb and resource ('Update a task') and immediately scopes it to partial updates ('Pass only the fields to change') with concrete examples (mark done, move between epics). It doesn't distinguish itself from near-neighbors like update_epic or update_open_question, but the mutating purpose is unambiguous.

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?

It gives explicit operational context: partial-update semantics, marking done via status='done', moving between epics, the assignment-scoping rule ('work only on items assigned to the user... see list_tasks assignee=me'), and a conditional requirement for status='blocked'. It names a sibling (list_tasks) but never rules out alternatives such as update_epic for epic-level changes.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources