Skip to main content
Glama

update_task

DestructiveIdempotent

Updates task fields such as title, priority, due date, labels, and custom fields, returning a lean confirmation by default or the complete task when requested.

Instructions

Update task fields. Returns a lean confirmation by default (id, status_id, assignee, updated_at) — the card's static fields are not echoed back; full=true or get_task returns them.

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

Input Schema

NameRequiredDescriptionDefault
fullNoReturn the complete updated task (all fields, verbatim) instead of the lean confirmation (id, status_id, assignee, updated_at).
titleNoNew title.
labelsNoNew labels.
task_idYesTask ID.
due_dateNoDue date in RFC3339 format. Pass an empty string to clear it.
priorityNoNew priority.
descriptionNoNew description.
start_afterNoHold the task out of the queue until this moment, RFC3339 with Z or an offset (2026-11-01T09:00:00+03:00). From an agent it must be the published time of an external event, given with start_after_evidence; not a retry or poll interval. Independent of due_date. An empty value is refused: clear a date with clear_start_after.
custom_fieldsNoCustom field values to update.
estimated_hoursNoEstimated hours.
delegation_levelNoRouting after work: auto, review, or supervised.
completion_signalNoMark agent-side work as finished.
start_after_originNoOptional, only agent_evidence. The server derives the origin from the caller; a person's date needs no evidence.
start_after_evidenceNoRequired by the server for an agent's start_after: {event_ref, source, why}, the same rules as wait_for on=time.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv0.1.7
    • changedInput schema / properties / start_after / description
      Previous value: -"Don't surface/feed this task before this RFC3339 timestamp. Independent of due_date. Pass an empty string to clear it."New value: +"Hold the task out of the queue until this moment, RFC3339 with Z or an offset (2026-11-01T09:00:00+03:00). From an agent it must be the published time of an external event, given with start_after_evidence; not a retry or poll interval. Independent of due_date. An empty value is refused: clear a date with clear_start_after."
    • addedInput schema / properties / start_after_evidence
      Added value: +{
      +  "description": "Required by the server for an agent's start_after: {event_ref, source, why}, the same rules as wait_for on=time.",
      +  "properties": {
      +    "event_ref": {
      +      "description": "The external event the moment belongs to, e.g. nightly-export (max 500 chars).",
      +      "type": "string"
      +    },
      +    "source": {
      +      "description": "Where the event's time is published: an https:// URL, comment:<uuid> or artifact:<uuid> written by someone else.",
      +      "type": "string"
      +    },
      +    "why": {
      +      "description": "What happens at start_after and why not earlier, 10 to 500 chars.",
      +      "type": "string"
      +    }
      +  },
      +  "type": "object"
      +}
    • addedInput schema / properties / start_after_origin
      Added value: +{
      +  "description": "Optional, only agent_evidence. The server derives the origin from the caller; a person's date needs no evidence.",
      +  "type": "string"
      +}
  2. First observedv0.1.1

TDQS

A3.6/5.0
Behavior4/5

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

Annotations already declare non-read-only, destructive, idempotent, closed-world, so the safety profile is covered. The description adds real value beyond that by disclosing the surprising default return behavior — a lean confirmation with only id, status_id, assignee, updated_at, not the full card — which an agent would otherwise misread as a truncated result. It stops short of explaining what "destructive" means here (e.g. whether labels/custom_fields replace or merge, whether omitted fields are preserved).

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?

Two sentences, front-loaded with the action and then the non-obvious return-value caveat; nothing is padded. The phrase "the card's static fields" leans on internal product vocabulary ("card") that is not defined anywhere in the definition, which slightly muddies an otherwise tight statement.

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?

With 14 parameters, nested objects, no output schema, and destructiveHint=true, the return-shape disclosure is necessary and well placed. What is missing is the semantic contract for a partial update — whether unset fields are left alone and whether labels/custom_fields overwrite wholesale — which matters most for a destructive multi-field mutation.

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 100% and the schema itself documents every parameter in detail, including the intricate start_after / start_after_evidence rules, so the baseline is 3. The description only reinforces the meaning of `full` (lean vs. verbatim full task), adding no new syntax or semantics for the other 13 parameters.

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?

"Update task fields" states a specific verb and resource, and the return-shape sentence signals this is the general field-mutation tool rather than a targeted action. It does not explicitly distinguish itself from siblings like assign_task, move_task, or finish_task, so an agent must infer that those narrower tools exist for their specific operations.

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

Usage Guidelines3/5

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

The definition routes the agent to an alternative for one narrow need — "full=true or get_task returns them" — which is genuine when-to-use guidance. However, it gives no guidance on when to call this versus the many targeted siblings (assign_task, move_task, finish_task), and no prerequisites or caveats for a destructive update.

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