Skip to main content
Glama

tasks_update

Idempotent

Update a task's status, title, body, blockers, or gate to track progress and unblock dependents; clearing a gate or final blocker makes dependent work ready.

Instructions

Update a task: change status (open|in_progress|done|dropped), edit title/body, add or remove dependencies, or set, edit or clear its gate. Moving to done/dropped closes it and unblocks its dependents; removing its last unfinished blocker makes it ready. Removing an id that is not one of its blockers changes nothing and is named back in not_depends_on; the ids removed are in removed_depends_on. Setting any gate_* field (re)opens the gate as it then reads; gate_clear=true clears an open gate once the person has acted, recording when, by this session, and gate_note: a step keeps its status and becomes ready once nothing else holds it, and a task of kind gate closes as done, which unblocks every task that depends on it. A task another session holds via a live claim is locked to its holder: updating it fails with 'already claimed' until the lease lapses or the holder releases it.

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": {
      "id": "<id>"
    },
    "name": "tasks_update"
  }
}

Input Schema

NameRequiredDescriptionDefault
idYestask id
bodyNonew body (aliases: content, text)
kindNostep (the default: work an agent claims and finishes) or gate (a person's action, or an event outside Seamless, that the tasks depending on it wait for: never ready and never claimed; gate_who and gate_what describe it, and clearing it closes it and unblocks its dependents)
titleNonew title
statusNonew status
projectNoreassign the task to another project slug (used when a split moves a project's open work to a child)
sessionNothe acting agent's session (the cc/<id> or cx/<id> on your briefing's 'Seam session' line, or a session name); needed only to mutate a task you hold a live claim on when several agents are active
gate_whoNowho must act before this task can go ahead: owner, founder:<name>, sitting:<name>, hardware, sealed:<project>, or free text (one line). With gate_what it gives the task a gate: a step whose gate is open is not ready, and tasks_ready lists it under gated
gate_noteNooptional, with gate_clear: what the person decided or did, kept with the cleared gate
gate_whatNowhat must happen, one line (with gate_who)
gate_clearNotrue: clear the task's open gate now that the person has acted (not with the gate_* edits)
session_idNothe acting agent's session ULID; takes precedence over session and the bound session
gate_decisionNooptional: the open question the person answers, one line
add_depends_onNotask ids to add as blockers (a comma-separated string is also accepted)
gate_ready_whenNooptional: when the task is ready, one line
remove_depends_onNotask ids to remove as blockers (a comma-separated string is also accepted); an id that is not a blocker of this task is a no-op, named back in not_depends_on

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed7 schema fields changedv0.10.1
    • addedInput schema / properties / gate_clear
      Added value: +{
      +  "description": "true: clear the task's open gate now that the person has acted (not with the gate_* edits)",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / gate_decision
      Added value: +{
      +  "description": "optional: the open question the person answers, one line",
      +  "type": "string"
      +}
    • addedInput schema / properties / gate_note
      Added value: +{
      +  "description": "optional, with gate_clear: what the person decided or did, kept with the cleared gate",
      +  "type": "string"
      +}
    • addedInput schema / properties / gate_ready_when
      Added value: +{
      +  "description": "optional: when the task is ready, one line",
      +  "type": "string"
      +}
    • addedInput schema / properties / gate_what
      Added value: +{
      +  "description": "what must happen, one line (with gate_who)",
      +  "type": "string"
      +}
    • addedInput schema / properties / gate_who
      Added value: +{
      +  "description": "who must act before this task can go ahead: owner, founder:<name>, sitting:<name>, hardware, sealed:<project>, or free text (one line). With gate_what it gives the task a gate: a step whose gate is open is not ready, and tasks_ready lists it under gated",
      +  "type": "string"
      +}
    • addedInput schema / properties / kind
      Added value: +{
      +  "description": "step (the default: work an agent claims and finishes) or gate (a person's action, or an event outside Seamless, that the tasks depending on it wait for: never ready and never claimed; gate_who and gate_what describe it, and clearing it closes it and unblocks its dependents)",
      +  "enum": [
      +    "step",
      +    "gate"
      +  ],
      +  "type": "string"
      +}
  2. Changed1 schema field changedv0.8.5
    • addedInput schema / properties / remove_depends_on
      Added value: +{
      +  "description": "task ids to remove as blockers (a comma-separated string is also accepted); an id that is not a blocker of this task is a no-op, named back in not_depends_on",
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
  3. First observedv0.1.0

TDQS

A4.4/5.0
Behavior5/5

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

Annotations only supply the generic safety profile (readOnly=false, idempotent=true, destructive=false), and the description goes well beyond them: it discloses downstream effects on dependents, readiness transitions, no-op semantics for unknown blocker ids with the returned not_depends_on/removed_depends_on fields, the exact 'already claimed' failure and its resolution, and gate clearing recording who acted and when. That is unusually rich behavioral context for a mutation tool.

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

Conciseness3/5

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

It is correctly front-loaded with the action list, but the second half collapses several distinct rules into long semicolon-chained sentences, notably the gate paragraph, where a step's status, readiness, and gate-kind closing behavior run together with the clearing record. Dense but not padded — the problem is parseability rather than verbosity.

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?

For a 16-parameter mutation tool with no output schema, the description covers the consequential behaviors an agent needs: status transitions, dependency edge cases, gate lifecycle, and claim-lock contention. It does supply partial return information (not_depends_on, removed_depends_on), but leaves unstated what a full successful response contains and whether session/session_id is required in the common single-agent case.

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

Parameters4/5

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

Schema description coverage is 100%, so the baseline is 3, and the description earns an increment by explaining cross-parameter interactions the schema does not: that any gate_* field (re)opens the gate, that gate_clear must not be combined with the gate_* edits, and that remove_depends_on of a non-blocker is a named no-op. The one weak spot is the dense 'Setting any gate_* field (re)opens the gate as it then reads' clause, which is harder to parse than the schema it supplements.

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?

The description opens with a specific verb+resource ('Update a task') and immediately enumerates the mutation surfaces: status, title/body, dependencies, and gate. That enumeration lets an agent distinguish it from tasks_add, tasks_claim, and tasks_ready without opening the schema.

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 clear situational context for the side effects of each edit (moving to done/dropped closes and unblocks dependents; removing the last blocker makes it ready) and states the failure condition when another session holds a live claim. It stops short of naming alternatives outright — it never says to use tasks_claim/tasks_release instead of editing a held task — so the routing is implied rather than explicit.

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