Skip to main content
Glama

tasks_update

Update a task's fields, append a comment, or upload and attach authorized file references. comment adds a comment without changing other fields. Status transitions to 'done' automatically stamp completed_at. Closing a task (status: 'done') takes a resolution_note — it's persisted as a comment AND included in the resolution email/webhook so the reporter knows what was done. Omitting it when transitioning to done returns a non-blocking suggestions entry asking for a resolution note.

Progress belongs in status_note (and health), not a comment per step. The three fields have distinct jobs: description is the living document (intent and contract, rewritten as the truth changes), status_note is the current state (overwritten each update, so one read tells you where things stand), and comments are append-only EVIDENCE — commit hashes, verification output, links. Appending status as comments is what makes a long-lived task unreadable: the thread renders oldest-first, so a reader meets the superseded version before the live one. Overwriting status_note loses nothing; the old value is kept in the activity log.

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

Input Schema

NameRequiredDescriptionDefault
areaNoNew subsystem tag, or empty string to clear.
typeNoNew type. Empty value leaves the type unchanged. Custom labels are supported. vision — why the organization exists. philosophy — a belief guiding trade-offs, including why it matters. directive — a rule or instruction, including what it supersedes. decision — a steer from the person who owns the project: their words, what it changes, what it replaces, the work it governs. sop — how to carry out a recurring job. spec — what to build and its acceptance criteria. roadmap — direction and outcomes for work ahead. epic — a larger outcome grouping related tasks. task — a concrete piece of current work. bug — behavior that needs correction. report — an observation, incident or customer finding. principle — a reusable rule for making decisions. learning — a lesson supported by experience or evidence. supplier — facts about an external service or supplier. content — a draft or plan for published material. policy — a standing rule governing operations. stance — a position on a subject and its reasoning. When the person who owns the project changes direction, parks or picks something, or overrules a plan, record it as a decision the same day, quoting them.
titleNoNew title.
authorNoOptional display label to attribute the comment to (e.g. "ci-bot", "support-agent"). Lets many entities that share one account self-identify on the thread. Only used when `comment` is supplied; defaults to the account.
due_atNoUnix timestamp (ms), or null to clear.
healthNoStructured progress signal independent of `status`; for example, a task can be in_progress and off_track. Omission means nobody has assessed it, while null clears an existing assessment.
labelsNoReplacement labels list. Completion guidance is explicit-label-only; in v1 requires-deployment is the machine-enforced gate.
statusNoWork records only. New status. 'blocked' represents work awaiting external action; 'needs_review' represents completed work awaiting sign-off.
commentNoIf supplied, appends a comment with this body.
task_idYesThe task ID.
assigneeNoNew assignee.
priorityNoNew priority.
parent_idNoNew parent task ID, or empty string to detach. A task may not be its own parent.
project_idYesProject ID (UUID), subdomain, or slug, resolved server-side; 'default' is the organization's shared task board.
shipped_inNoThe deploy/version in which this work shipped, represented by the deploy object tag such as "v7". It exposes child reports for review-for-closure. An empty string clears it.
waiting_onNoExplicitly waiting for human input, a product decision, or an external dependency. status_note records what is needed; clear with null or an empty string when resolved. Does not change assignee or status.
attachmentsNoReplacement task attachments as sw.fs paths. An empty array clears them.
descriptionNoNew description.
status_noteNoCurrent state in one short paragraph, overwritten rather than appended as work progresses. Prior values remain in the activity log. The 2000-character cap distinguishes this status line from the living `description`; an empty string clears it.
relationshipNoOne typed relationship from this task to another task in the same project.
superseded_byNoTask ID of the row that replaces this one (a newer spec, a corrected directive). Empty string clears it.
guidance_reviewNoReview of the exact current guidance draft, identified by guidance_version.draft.content_revision. Editing and reviewing are separate calls. Records the reviewing account; human approval is separate. Later edits remain drafts against the reviewed version.
resolution_noteNoShort outcome explanation for a task closing with status='done'. It persists as a comment and appears in the resolution notification email and webhook payload.
guidance_contextNoOptional guidance used or a scoped exception, recorded during a normal task update. Older basis remains visible beside current guidance. Exceptions inherit through parent/child links and need reassessment when guidance changes; they do not rewrite the SOP. Links and activity are recorded automatically.
deployment_versionNoSuccessful production version number of deployment_project_id, verified before task update or closure and available from project_deploys.
upload_attachmentsNoNative connector files to upload and append in this call. The top-level array contains authorized file-reference objects identified by openai/fileParams metadata. Each file is stored privately under /tasks/{task_id}/attachments/<name>; saved sw.fs paths are returned and appended. Binary bytes stay outside conversational context, and path/base64 strings are rejected.
deployment_project_idNoAccessible project whose successful deploy proves the work is live: ID, subdomain, or slug. It may differ from the task-owning project and always does on the deploy-less shared board. The task's project is the default.
remove_relationship_idNoIdentifier of one explicit relationship to delete. A parent_id-backed child_of edge is removed by clearing parent_id instead.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.5/5.0
Behavior4/5

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

Annotations cover only the mutation/safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the description carries the rest and does so well: completed_at auto-stamping, resolution_note being persisted as a comment and surfaced in email/webhook, prior status_note values retained in the activity log, and attachments stored privately under /tasks/{task_id}/attachments with sw.fs paths returned. It does not explain overall response shape or what a partial update returns, which is the remaining gap rather than an omission of behavior.

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-loaded with a one-sentence capability summary before the detail, which is the right shape for a 28-parameter tool. The middle paragraph is persuasive prose ('Appending status as comments is what makes a long-lived task unreadable') that justifies its length as guidance but is more wordy than strictly needed.

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 28-parameter mutation tool with nested objects and no output schema, the description covers the highest-risk behaviors: closing semantics, comment attribution, clearing fields via empty values, and attachment handling. It leaves the return payload largely unexplained beyond the attachment path claim, which an agent must infer from the schema alone.

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% across 28 parameters, so the baseline is 3; the description earns above that by explaining semantics the schema only hints at — the deliberate division of labor between description, status_note, and comment, and the notification consequence of resolution_note. It does not attempt to disambiguate the many other fields (waiting_on vs status, guidance_context vs guidance_review) at that same depth.

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?

Opens with a specific verb plus resource and enumerates the three modes of the call: field update, comment append, and attachment upload. An agent can distinguish this from tasks_create, tasks_get, and tasks_list without reading the schema, and the closing/resolution behavior is named as a distinct case.

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 explicit when-to-use guidance for the three overlapping write paths — description as living document, status_note as overwritten current state, comment as append-only evidence — and explains the failure mode of conflating them. It also states the conditional around closing: a resolution_note is expected when transitioning to done, and omission yields a non-blocking suggestion rather than an error.

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