Skip to main content
Glama

Update Task Tool

update_task
Idempotent

Edit an existing task's title, details, status, assignee, project, checklist steps, files, or comments to keep work items current and correctly routed.

Instructions

Changes a task: edit its title or details (title, notes: the whole new text, read it first with start_task or list_tasks; add_steps appends new - [ ] steps), take it (assignee "me", status "doing"), move it (todo, doing, blocked with a reason, done, dropped; todo turns an idea into a task), move it to another project (move_to_project), remove its files you added (remove_files; to swap a changed file, use add_attachment with replaces instead), give it to someone ("none" frees it), tick its steps (check) or comment on it. Progress on a task with steps is shown by ticking the finished steps (check: [numbers]), not by listing them in a comment; a comment is for questions, answers and what the steps do not cover; while working on your own, do not comment on every small change: one comment when there is a result or a question. Before giving a task to someone else, when it has gathered several comments or file versions, ask the person once whether to leave a handoff note (handoff: what is done, what is left, which file is the final one) and mark the earlier files as older versions (old_files); nothing is deleted. Only when the person asked for 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": "update_task"
  }
}

Input Schema

NameRequiredDescriptionDefault
idYesTask number, e.g. 12.
dueNoA due date, YYYY-MM-DD, or "none" to remove it.
checkNoStep numbers (from 1, as start_task lists them) to tick in the task's checklist, when they are finished.
notesNoThe task's new details (its description), in Markdown: the whole text, replacing the old one. Read the current details first (start_task or list_tasks) and keep what should stay, including the - [ ] / - [x] steps; an empty string clears them. Only when the person asks.
proofNoWith status done: the proof - the commit, the address where the change shows, or a short note. Kept on the task.
titleNoA new title, when the person wants it renamed.
reasonNoWhat a blocked task is waiting for.
repeatNoMakes the task come back: when it is done, the next one is added, due one interval later; "none" stops it.
statusNotodo also turns an idea into a task.
commentNoA comment on the task (a question, a clarification, an answer), in Markdown; colleagues and, on projects visible to the client, the client see it. Not for reporting finished steps: tick them with check (both can go in the same call). Only when the person asks.
handoffNoA handoff note, usually with assignee when the task goes to someone else: what is done, what is left, which file is the final one (by name), in Markdown. Whoever opens the task sees it first, above the comments. Only after the person agreed.
uncheckNoStep numbers to untick, if ticked by mistake.
assigneeNo"me", a colleague's name or email, or "none" to free the task.
add_stepsNoNew steps to append to the task's checklist, unticked (just the text of each). Use it instead of notes when only steps are added.
old_filesNoIds of the task's files that are earlier versions (from read_task): they stay on the task, shown under the current ones as older versions, so whoever takes it over knows which file is the final one. Nothing is deleted. Only after the person agreed.
remove_filesNoIds of the task's files to remove (from start_task: those with can_replace). Only the files you added, and only while the task is open: on a closed task they stay as reference. To put a new version in place of a file, use add_attachment with replaces instead.
move_to_projectNoMoves the task, with its files, to another project (slug or name) the person can see. Whoever does it stays on it only if they work on that project too. Only when the person asks.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.1.425
    • addedInput schema / properties / handoff
      Added value: +{
      +  "description": "A handoff note, usually with assignee when the task goes to someone else: what is done, what is left, which file is the final one (by name), in Markdown. Whoever opens the task sees it first, above the comments. Only after the person agreed.",
      +  "type": "string"
      +}
    • addedInput schema / properties / old_files
      Added value: +{
      +  "description": "Ids of the task's files that are earlier versions (from read_task): they stay on the task, shown under the current ones as older versions, so whoever takes it over knows which file is the final one. Nothing is deleted. Only after the person agreed.",
      +  "items": {
      +    "type": "integer"
      +  },
      +  "type": "array"
      +}
  2. First observedv0.1.0

TDQS

A3.8/5.0
Behavior1/5

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

The annotations declare idempotentHint=true, but the description explicitly describes additive, non-idempotent operations: add_steps 'appends new' checklist items and comment adds a comment. Repeating the same call with those parameters would create duplicate steps or comments, so the description contradicts the idempotency annotation. This is an Annotation Contradiction.

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?

The main action is front-loaded, but the description is a dense single paragraph with nested parentheticals and a trailing 'Only when the person asked for it' whose scope is unclear. Much of the content is useful for a 17-parameter tool, yet the run-on structure hurts scanability and makes the guidance harder to parse than necessary.

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 17-parameter mutation tool with no output schema, the description covers most important workflow and visibility rules, including client-visible comments, non-deletion of files, handoff agreement, and file version marking. It still omits return or error behavior and leaves some parameter effects to the schema, so it is strong but not fully complete.

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 parameter meanings are already documented; nevertheless the description adds meaningful cross-parameter workflow semantics. For example, notes replaces the whole text and should be read first, add_steps should be used instead of notes when only steps are added, check replaces reporting finished steps in comments, and remove_files points to add_attachment/replaces. It does not add narrative meaning for due, proof, reason, repeat, or uncheck beyond the schema, so it is not a 5.

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 and resource, 'Changes a task,' and enumerates the sub-operations it supports: editing title or details, assigning, moving status, moving project, removing files, ticking steps, commenting. It also names relevant alternatives such as start_task/list_tasks for reading and add_attachment with replaces for swapping files, so an agent can distinguish its role from siblings.

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?

It gives explicit when-to-use and when-not-to-use guidance: tick finished steps with check rather than reporting them in a comment; use add_attachment with replaces instead of remove_files for swapping a file; handoff and old_files only after the person agrees; notes, comment, and move_to_project only when the person asks. It also provides etiquette guidance about not commenting on every small change.

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