Tirith

Official

Overview Schema Source Related Servers Discussions Admin

task_update

Idempotent

Change a task's status for parallel coding agents: mark done, hand back to todo, block with reason, or claim in_progress by id, avoiding conflicts and tracking ownership.

Instructions

Change one task's status: done to finish it, todo to hand it back, blocked to park it with note as the reason, in_progress to take it by id. Changing a task another agent has in_progress is a conflict naming the owner, unless force, which is recorded in the task's notes, lead-only while a swarm has a lead. To get the next task without naming one use task_pull. Returns the task in full.

Input Schema

Name	Required	Description
`note`	No	A note to append. For `blocked`, this is the reason.
`agent`	Yes	Your stable agent name.
`force`	No	Take or close a task another agent has in progress.
`status`	Yes	One of `todo`, `in_progress`, `blocked`, `done`.
`task_id`	Yes	The task's id, or a unique prefix of it.

Output Schema

Name	Required	Description
`lead`	No	On a lead-only conflict: the lead to message.
`task`	No	The task after the change: id, title, description, priority, depends_on, paths, created_by, created_at, updated_at, notes, and state: its status with owner (in_progress), owner and reason (blocked), or by (done).
`owner`	No	On conflict: the agent that has the task in_progress.
`since`	No	On conflict: RFC 3339 time that agent took it.
`status`	Yes	ok. conflict: another agent has it in_progress and force was not set, or force is lead-only. not_found: no such task. invalid: bad status or an ambiguous id prefix.
`message`	No	Human-readable detail, on most outcomes other than ok.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv1.3.0Oct 16, 2026

addedOutput schema / properties / lead

Added value: +{
+  "description": "On a lead-only conflict: the lead to message."
+}

changedOutput schema / properties / status / description

Previous value: -"ok. conflict: another agent has it in_progress and force was not set. not_found: no such task. invalid: bad status or an ambiguous id prefix."New value: +"ok. conflict: another agent has it in_progress and force was not set, or force is lead-only. not_found: no such task. invalid: bad status or an ambiguous id prefix."

Changed7 schema fields changedv1.1.2Sep 18, 2026

addedInput schema / properties / agent / description
```
Added value: +"Your stable agent name."
```

addedInput schema / properties / force / description

Added value: +"Take or close a task another agent has in progress."

addedInput schema / properties / note / description

Added value: +"A note to append. For `blocked`, this is the reason."

addedInput schema / properties / status / description

Added value: +"One of `todo`, `in_progress`, `blocked`, `done`."

addedInput schema / properties / status / enum

Added value: +[
+  "todo",
+  "in_progress",
+  "blocked",
+  "done"
+]

addedInput schema / properties / task_id / description

Added value: +"The task's id, or a unique prefix of it."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "description": "Any result may also carry lost, inbox, inbox_more and persist_error; see guide.",
+  "properties": {
+    "message": {
+      "description": "Human-readable detail, on most outcomes other than ok.",
+      "type": "string"
+    },
+    "owner": {
+      "description": "On conflict: the agent that has the task in_progress."
+    },
+    "since": {
+      "description": "On conflict: RFC 3339 time that agent took it."
+    },
+    "status": {
+      "description": "ok. conflict: another agent has it in_progress and force was not set. not_found: no such task. invalid: bad status or an ambiguous id prefix.",
+      "enum": [
+        "ok",
+        "conflict",
+        "not_found",
+        "none",
+        "invalid",
+        "cancelled"
+      ],
+      "type": "string"
+    },
+    "task": {
+      "description": "The task after the change: id, title, description, priority, depends_on, paths, created_by, created_at, updated_at, notes, and state: its status with owner (in_progress), owner and reason (blocked), or by (done).",
+      "type": "object"
+    }
+  },
+  "required": [
+    "status"
+  ],
+  "type": "object"
+}

First observedv1.1.1Sep 18, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations only declare idempotentHint and destructiveHint=false; the description adds substantial behavioral context beyond them: a competing in_progress task is a conflict naming its owner, force overrides it but is recorded in the task's notes, and force is lead-only while a swarm has a lead. That covers conflict semantics, audit trail, and authorization, which structured fields do not provide.

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-loads the core action and each status transition succinctly, with the conflict/force rules and the sibling pointer following. It is dense but every clause carries information; the long final sentences are slightly run-on but not wasteful.

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

Completeness5/5

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

With an output schema present, return values need not be explained (though "Returns the task in full" is a nice touch), and annotations cover the safety profile. The description fills the remaining gaps: per-status intent, conflict handling, force authorization, and the cross-reference to task_pull.

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 coverage is 100%, so baseline is 3, but the description adds operational meaning the schema lacks: status values are given behavioral semantics rather than just an enum list, note is tied to blocked as its reason, and force is explained as taking/closing another agent's in-progress task. This meaningfully enriches the enum and force parameters beyond the schema text.

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 ("Change one task's status") and enumerates the four target states with their operational meaning. It explicitly contrasts with task_pull ("To get the next task without naming one use task_pull"), so the agent can distinguish it from sibling task tools without opening any schema.

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

Usage Guidelines5/5

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

Gives when-to-use guidance per status value (done to finish, todo to hand back, blocked to park with reason, in_progress to take by id) and names the alternative tool for pulling the next task. It also states the conflict precondition and the force/lead-only escape hatches, leaving little to inference.

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