Skip to main content
Glama
idea-base-mcp-server

idea-base-mcp-server

Official

update_task

Modify an existing task's details—title, description, dates, estimates, priority, assignees, subtasks, GitHub issue/PR links, or acceptance criteria—by task ID, with optional clearing of fields.

Instructions

Update task details like title, description, estimates, or acceptance criteria.

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
titleNoNew title for the task
task_idYesThe ID of the task to update
due_dateNoNew due date as YYYY-MM-DD. Pass an empty string to clear it.
priorityNoNew priority level (0-5, higher is more important)
blocked_byNoREPLACES the full set of tasks this task is blocked by. Pass [] to clear all of them. Every id must be a task in the same product; a circular chain (A blocked by B blocked by A) is rejected. While any of these is not done, the task shows as blocked whatever its stored status says.
sort_orderNoPosition among the project's tasks (lower sorts first). Drives the order returned by list_tasks and the board/list views.
start_dateNoNew start date as YYYY-MM-DD. Pass an empty string to clear it.
descriptionNoNew description
is_milestoneNoMark this task as a milestone, drawn differently on the Gantt view. Pass false to unmark it.
github_pr_urlNoURL of the GitHub Pull Request implementing this task. Used to fetch the PR diff for AI verification and to match incoming CI status back to this task. Pass an empty string to clear it.
blocked_reasonNoFree-text reason shown next to a manually-set Blocked status ("waiting on the client"). Cleared automatically when the task leaves the blocked status.
parent_task_idNoRE-PARENT this existing task: make it a subtask of the given task, or pass null to detach it back to top level. Until GH #387 this was settable only at creation (create_task), which meant a finding recognised as adjacent AFTER it was written down could not be filed under the task that found it. The parent must be in the SAME project, cannot itself be a subtask, and THIS task must not already have subtasks of its own — nesting is one level only, and each of those is refused with a 400 naming what is in the way rather than silently producing a grandchild. Note that parenting a task immediately stops its parent closing: a parent with any subtask that is not done is refused (403 OPEN_SUBTASKS) by PUT /api/tasks/:id/status.
github_issue_idNoThe GitHub issue number this task tracks (pass null or an empty string to unlink). LOAD-BEARING, not bookkeeping: session_heartbeats.task_id is NOT NULL and the heartbeat endpoint resolves a session's GitHub issue number to a task through tasks.github_issue_id — so a session working an issue whose task lacks this column emits heartbeats that have nowhere to land and is invisible on the live agent board. Writable over REST since #384; this tool could not send it until GH #387, which is why it had to be set with a hand-rolled curl.
assignee_user_idNoUser ID to assign the task to, REPLACING THE WHOLE assignee set (every non-active assignment row is deleted, active workers spared) — use this only when you want exactly one owner. Must be a member of the same account. Pass an empty string to unassign everyone (active workers still spared). To ADD a second assignee without touching the first, use add_assignee instead; to remove just one, use remove_assignee.
github_issue_urlNoFull URL of the GitHub issue this task tracks. Pass an empty string to clear it. Set it alongside github_issue_id so the two cannot disagree.
estimated_minutesNoNew time estimate in minutes
verification_modeNoGate this task's own completion. "manual" (default) allows a plain status change to done. "ai_review" or "all" BLOCK marking the task done (403 VERIFICATION_REQUIRED) until ai_completion_score reaches 0.8 — run "Verify with AI" first. "ci_required" or "all" BLOCK it until a PR is linked (github_pr_url) with passing CI. Setting this arms a real check against your own future attempt to close the task.
required_ci_checksNoWhich named CI checks (matched case-insensitively as a substring of the check name) must pass for "ci_required"/"all" verification_mode to consider CI satisfied — e.g. ["build","test"]. Read by GET /api/tasks/:id/ci-status's resolveRequiredChecks (app/functions/api/tasks/[id]/ci-status.js:13-32), NOT by the GitHub webhook handler, which sets ci_status unconditionally from whichever single check/workflow event just arrived regardless of this field. Stored as a JSON array. Pass an empty array to require every check; this tool has no way to clear the column back to "inherit from project" (the REST API reserves that for an empty string, which this array-typed field cannot send).
acceptance_criteriaNoNew acceptance criteria

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv2.7.0
    • addedInput schema / properties / github_issue_id
      Added value: +{
      +  "description": "The GitHub issue number this task tracks (pass null or an empty string to unlink). LOAD-BEARING, not bookkeeping: session_heartbeats.task_id is NOT NULL and the heartbeat endpoint resolves a session's GitHub issue number to a task through tasks.github_issue_id — so a session working an issue whose task lacks this column emits heartbeats that have nowhere to land and is invisible on the live agent board. Writable over REST since #384; this tool could not send it until GH #387, which is why it had to be set with a hand-rolled curl.",
      +  "type": [
      +    "number",
      +    "string",
      +    "null"
      +  ]
      +}
    • addedInput schema / properties / github_issue_url
      Added value: +{
      +  "description": "Full URL of the GitHub issue this task tracks. Pass an empty string to clear it. Set it alongside github_issue_id so the two cannot disagree.",
      +  "type": "string"
      +}
    • addedInput schema / properties / parent_task_id
      Added value: +{
      +  "description": "RE-PARENT this existing task: make it a subtask of the given task, or pass null to detach it back to top level. Until GH #387 this was settable only at creation (create_task), which meant a finding recognised as adjacent AFTER it was written down could not be filed under the task that found it. The parent must be in the SAME project, cannot itself be a subtask, and THIS task must not already have subtasks of its own — nesting is one level only, and each of those is refused with a 400 naming what is in the way rather than silently producing a grandchild. Note that parenting a task immediately stops its parent closing: a parent with any subtask that is not done is refused (403 OPEN_SUBTASKS) by PUT /api/tasks/:id/status.",
      +  "type": [
      +    "number",
      +    "null"
      +  ]
      +}
  2. Changed6 schema fields changedv2.2.0
    • changedInput schema / properties / assignee_user_id / description
      Previous value: -"User ID to assign the task to, replacing any existing assignee. Must be a member of the same account. Pass an empty string to unassign."New value: +"User ID to assign the task to, REPLACING THE WHOLE assignee set (every non-active assignment row is deleted, active workers spared) — use this only when you want exactly one owner. Must be a member of the same account. Pass an empty string to unassign everyone (active workers still spared). To ADD a second assignee without touching the first, use add_assignee instead; to remove just one, use remove_assignee."
    • addedInput schema / properties / github_pr_url
      Added value: +{
      +  "description": "URL of the GitHub Pull Request implementing this task. Used to fetch the PR diff for AI verification and to match incoming CI status back to this task. Pass an empty string to clear it.",
      +  "type": "string"
      +}
    • addedInput schema / properties / is_milestone
      Added value: +{
      +  "description": "Mark this task as a milestone, drawn differently on the Gantt view. Pass false to unmark it.",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / required_ci_checks
      Added value: +{
      +  "description": "Which named CI checks (matched case-insensitively as a substring of the check name) must pass for \"ci_required\"/\"all\" verification_mode to consider CI satisfied — e.g. [\"build\",\"test\"]. Read by GET /api/tasks/:id/ci-status's resolveRequiredChecks (app/functions/api/tasks/[id]/ci-status.js:13-32), NOT by the GitHub webhook handler, which sets ci_status unconditionally from whichever single check/workflow event just arrived regardless of this field. Stored as a JSON array. Pass an empty array to require every check; this tool has no way to clear the column back to \"inherit from project\" (the REST API reserves that for an empty string, which this array-typed field cannot send).",
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • addedInput schema / properties / sort_order
      Added value: +{
      +  "description": "Position among the project's tasks (lower sorts first). Drives the order returned by list_tasks and the board/list views.",
      +  "type": "number"
      +}
    • addedInput schema / properties / verification_mode
      Added value: +{
      +  "description": "Gate this task's own completion. \"manual\" (default) allows a plain status change to done. \"ai_review\" or \"all\" BLOCK marking the task done (403 VERIFICATION_REQUIRED) until ai_completion_score reaches 0.8 — run \"Verify with AI\" first. \"ci_required\" or \"all\" BLOCK it until a PR is linked (github_pr_url) with passing CI. Setting this arms a real check against your own future attempt to close the task.",
      +  "enum": [
      +    "manual",
      +    "ai_review",
      +    "ci_required",
      +    "all"
      +  ],
      +  "type": "string"
      +}
  3. Changed6 schema fields changedv1.3.0
    • addedInput schema / properties / assignee_user_id
      Added value: +{
      +  "description": "User ID to assign the task to, replacing any existing assignee. Must be a member of the same account. Pass an empty string to unassign.",
      +  "type": "string"
      +}
    • addedInput schema / properties / blocked_by
      Added value: +{
      +  "description": "REPLACES the full set of tasks this task is blocked by. Pass [] to clear all of them. Every id must be a task in the same product; a circular chain (A blocked by B blocked by A) is rejected. While any of these is not done, the task shows as blocked whatever its stored status says.",
      +  "items": {
      +    "type": "number"
      +  },
      +  "type": "array"
      +}
    • addedInput schema / properties / blocked_reason
      Added value: +{
      +  "description": "Free-text reason shown next to a manually-set Blocked status (\"waiting on the client\"). Cleared automatically when the task leaves the blocked status.",
      +  "type": "string"
      +}
    • addedInput schema / properties / due_date
      Added value: +{
      +  "description": "New due date as YYYY-MM-DD. Pass an empty string to clear it.",
      +  "type": "string"
      +}
    • changedInput schema / properties / priority / description
      Previous value: -"New priority level"New value: +"New priority level (0-5, higher is more important)"
    • addedInput schema / properties / start_date
      Added value: +{
      +  "description": "New start date as YYYY-MM-DD. Pass an empty string to clear it.",
      +  "type": "string"
      +}
  4. First observedv1.2.0

TDQS

C2.9/5.0
Behavior2/5

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

No annotations are supplied, so the description carries the full behavioral burden and it drops it. It doesn't state that this is a mutation, whether omitted fields are left unchanged, that some fields replace entire sets (blocked_by, assignee_user_id), that clearing is done with empty strings/null, or that parenting can trigger 403 OPEN_SUBTASKS and 400 nesting refusals. All of that critical behavior is buried in schema text the agent may never read before committing a write.

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?

A single well-formed sentence with the verb and resource front-loaded and zero filler. It is efficient rather than padded, though the efficiency is achieved by omission on a 19-parameter mutation tool.

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

Completeness2/5

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

For a write tool with 19 parameters, replacement semantics, clearing conventions, verification gates, and multiple 4xx failure modes, one sentence is far from sufficient — especially with no annotations and no output schema to fall back on. An agent acting on the description alone would not know it is performing a partial-update mutation that can wipe assignee or blocker sets.

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 per-parameter text is unusually rich (replacement semantics, clearing conventions, verification gating, error codes), so the schema already does the heavy lifting; baseline 3 applies. The description adds no meaning beyond the schema — its four named fields are a strict subset of the 19 parameters and introduce no format or constraint information.

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 details" is a specific verb plus resource, and the examples (title, description, estimates, acceptance criteria) confirm the target objects. It never distinguishes itself from siblings like update_task_status, add_assignee, or remove_assignee, which also mutate a task, so an agent cannot tell from the description alone which of those to reach for.

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

Usage Guidelines2/5

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

There is no when-to-use guidance at all: nothing says when to prefer this over update_task_status for status changes, or over add_assignee/remove_assignee for assignees (even though one parameter explicitly replaces the whole assignee set). The only hint of routing lives inside a parameter description, not the tool description.

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