pm_task
{"content":"{{\u003c badge content=\"Vanguard\" color=\"blue\" class=\"tier-badge\" \u003e}}\n\nThe `pm_task` tool is the workhorse of the Valdr MCP surface. It covers the full task lifecycle — creation, search, status transitions, checklists, comments, and event history. Every agent session runs against a task, so this is the most-called tool in most workflows.\n\n{{\u003c callout type=\"info\" \u003e}}\nMost actions look up tasks by `taskKey` (e.g., `\"PROJ-123\"`). `plan` accepts either `taskId` or `taskKey`.\n{{\u003c /callout \u003e}}\n\n## Actions\n\n`create`, `get`, `plan`, `get_prompt`, `update`, `delete`, `search`, `change_status`, `checklist_toggle`, `checklist_lookup`, `event_list`, `comment_create`, `comment_list`, `comment_delete`, `help`\n\n---\n\n## create\n\nCreate a new task under a project.\n\n### Parameters\n\n| Field | Type | Required | Notes |\n|-------|------|----------|-------|\n| `projectKey` | string | Yes | Project this task belongs to (e.g., `\"PROJ\"`) |\n| `title` | string | Yes | Short task title |\n| `key` | string | No | Custom task key — auto-generated if omitted |\n| `description` | string | No | Markdown description with acceptance criteria |\n| `type` | string | No | `task` (default), `bug`, `story`, `epic`, or `spike` |\n| `status` | string | No | `backlog` (default), `to_do`, `in_progress`, `in_review`, `verified`, `done` |\n| `sprintId` | string | No | Link to a sprint at creation |\n| `points` | number | No | Story points |\n| `priority` | number | No | 1–5 |\n| `assignee` | string | No | Agent handle |\n| `reporter` | string | No | Agent handle |\n| `metadata` | object | No | `{ tags?, links?, checklists? }` |\n\n### Example\n\n```text\npm_task {\n action: \"create\",\n projectKey: \"MYAPI\",\n title: \"Add rate limiting to /auth endpoints\",\n description: \"Implement per-IP rate limiting on signup and login endpoints.\",\n type: \"task\",\n status: \"to_do\",\n priority: 2,\n assignee: \"sigrid\"\n}\n```\n\n---\n\n## get\n\nFetch a task by key.\n\n### Parameters\n\n| Field | Type | Required |\n|-------|------|----------|\n| `taskKey` | string | Yes |\n\n---\n\n## plan\n\nGet the linked plan for a task (if one exists). Plans come from the [vmp planner](../planner/).\n\n### Parameters\n\n| Field | Type | Required | Notes |\n|-------|------|----------|-------|\n| `taskId` | string | Conditional | Task ULID. Required if `taskKey` is omitted. |\n| `taskKey` | string | Conditional | Alternative lookup. Required if `taskId` is omitted. |\n\n---\n\n## get_prompt\n\nBuild the task-specific system prompt that agents receive when launched against this task. Includes description, acceptance criteria, linked requirements, and context.\n\n### Parameters\n\n| Field | Type | Required |\n|-------|------|----------|\n| `taskKey` | string | Yes |\n\nThis is useful for agents that want to see what an executor would receive before launching.\n\n---\n\n## update\n\nUpdate task fields. Pass only the fields you want to change.\n\n### Parameters\n\n| Field | Type | Required |\n|-------|------|----------|\n| `taskKey` | string | Yes |\n| `description` | string | No |\n| `assignee` | string | No |\n| `reporter` | string | No |\n| `points` | number \\| null | No |\n| `priority` | number \\| null | No |\n| `metadata` | object | No |\n\nUse `change_status` to change status. Use [`pm_sprint.link_task`](../sprints/#link_task) to change sprint membership.\n\n---\n\n## delete\n\nDelete a task permanently. This action is reserved for intentional cleanup, not normal lifecycle movement. Fetch the task first with `get` and confirm the key, project, sprint, and checklist state before deleting it.\n\n{{\u003c callout type=\"warning\" \u003e}}\n`delete` is permanent. Use it only after a confirming `pm_task { action: \"get\" }` shows you are removing the intended task. To move work through the lifecycle, use `change_status` instead.\n{{\u003c /callout \u003e}}\n\n### Parameters\n\n| Field | Type | Required |\n|-------|------|----------|\n| `taskKey` | string | Yes |\n\n### Example\n\n```text\npm_task { action: \"get\", taskKey: \"MYAPI-42\" }\npm_task { action: \"delete\", taskKey: \"MYAPI-42\" }\n```\n\n---\n\n## search\n\nSearch tasks within a project.\n\n### Parameters\n\n| Field | Type | Required | Notes |\n|-------|------|----------|-------|\n| `projectKey` | string | Yes | Scope to a specific project |\n| `query` | string | No | Search text |\n| `status` | string | No | Filter by status |\n| `sprintId` | string | No | Filter by sprint |\n| `limit` | number | No | Result cap |\n\n### Example\n\n```text\npm_task {\n action: \"search\",\n projectKey: \"MYAPI\",\n status: \"in_progress\",\n limit: 20\n}\n```\n\n---\n\n## change_status\n\nTransition a task through the status lifecycle: `backlog → to_do → in_progress → in_review → verified → done`.\n\n### Parameters\n\n| Field | Type | Required | Notes |\n|-------|------|----------|-------|\n| `taskKey` | string | Yes | |\n| `to` | string | Yes | Target status |\n| `reason` | string | No | Reason for the change |\n\n### Example\n\n```text\npm_task {\n action: \"change_status\",\n taskKey: \"MYAPI-42\",\n to: \"in_review\",\n reason: \"Implementation complete, ready for code review\"\n}\n```\n\n---\n\n## checklist_toggle\n\nToggle an individual checklist item on a task.\n\n### Parameters\n\n| Field | Type | Required |\n|-------|------|----------|\n| `taskKey` | string | Yes |\n| `checklistId` | string | Yes |\n| `itemId` | string | Yes |\n| `checked` | boolean | Yes |\n\n---\n\n## checklist_lookup\n\nLook up checklist names, items, or templates.\n\n### Parameters\n\n| Field | Type | Required | Notes |\n|-------|------|----------|-------|\n| `mode` | string | No | `names` (default), `items`, or `template` |\n| `query` | string | No | Search query |\n| `checklistName` | string | Conditional | Required for `template` mode |\n| `limit` | number | No | Result cap |\n\n### Example\n\n```text\npm_task {\n action: \"checklist_lookup\",\n mode: \"template\",\n checklistName: \"code-review\"\n}\n```\n\n---\n\n## event_list\n\nFetch the audit trail of events for a task — status changes, assignee changes, comments, session launches, and more.\n\n### Parameters\n\n| Field | Type | Required | Notes |\n|-------|------|----------|-------|\n| `taskKey` | string | Yes | |\n| `limit` | number | No | Default 25, max 100 |\n\n---\n\n## comment_create / comment_list / comment_delete\n\nManage task and task-review comments. Comments can be scoped to a review or assignment for threaded discussion.\n\n### comment_create\n\n| Field | Type | Required | Notes |\n|-------|------|----------|-------|\n| `taskKey` | string | Yes | |\n| `body` | string | Yes | |\n| `reviewId` | string | No | Scope to a specific review |\n| `assignmentId` | string | No | Scope to a reviewer assignment |\n| `parentCommentId` | string | No | For threaded replies |\n| `actorHandle` | string | No | Who is commenting |\n\n### comment_list\n\n| Field | Type | Required | Notes |\n|-------|------|----------|-------|\n| `taskKey` | string | Yes | |\n| `reviewId` | string | No | Filter by review |\n| `assignmentId` | string | No | Filter by assignment |\n\n### comment_delete\n\n| Field | Type | Required | Notes |\n|-------|------|----------|-------|\n| `taskKey` | string | Yes | |\n| `commentId` | string | Yes | |\n| `actorHandle` | string | No | Who is deleting |\n\nDeleting a comment also deletes its replies.\n\n---\n\n## help\n\n```text\npm_task { action: \"help\" }\n```\n\n`help` returns structured, read-only guidance that agents can inspect before calling task actions.\n\n| Field | Contents |\n|-------|----------|\n| `actions` | Current accepted action names, including `delete`, `checklist_lookup`, `comment_delete`, and `help` |\n| `whenToUse` | One-line guidance for core actions such as `get`, `get_prompt`, `change_status`, `checklist_toggle`, and `comment_create` |\n| `examples` | Representative calls, including fetching a task, moving it to review, and toggling a checklist item |\n| `cautions` | Guardrails such as fetch-before-update, fresh `clientRequestId` values, and using sprint link/unlink operations instead of task updates |\n| `compatibility` | Stability notes for the additive help payload and MCP error behavior |\n\nUse this payload as the live reference when building agents that need to discover the task surface before mutating work.\n\n## Related\n\n- [pm_session](../sessions/) — launch agent sessions against tasks\n- [pm_review](../reviews/) — start reviews on completed tasks\n- [pm_sprint](../sprints/) — link tasks to sprints","description":"Full task lifecycle: create, update, transition status, manage checklists, and track events.","title":"pm_task"}
Vanguard
The pm_task tool is the workhorse of the Valdr MCP surface. It covers the full task lifecycle — creation, search, status transitions, checklists, comments, and event history. Every agent session runs against a task, so this is the most-called tool in most workflows.
Most actions look up tasks by
taskKey (e.g., "PROJ-123"). plan accepts either taskId or taskKey.Actions
create, get, plan, get_prompt, update, delete, search, change_status, checklist_toggle, checklist_lookup, event_list, comment_create, comment_list, comment_delete, help
create
Create a new task under a project.
Parameters
| Field | Type | Required | Notes |
|---|---|---|---|
projectKey | string | Yes | Project this task belongs to (e.g., "PROJ") |
title | string | Yes | Short task title |
key | string | No | Custom task key — auto-generated if omitted |
description | string | No | Markdown description with acceptance criteria |
type | string | No | task (default), bug, story, epic, or spike |
status | string | No | backlog (default), to_do, in_progress, in_review, verified, done |
sprintId | string | No | Link to a sprint at creation |
points | number | No | Story points |
priority | number | No | 1–5 |
assignee | string | No | Agent handle |
reporter | string | No | Agent handle |
metadata | object | No | { tags?, links?, checklists? } |
Example
pm_task {
action: "create",
projectKey: "MYAPI",
title: "Add rate limiting to /auth endpoints",
description: "Implement per-IP rate limiting on signup and login endpoints.",
type: "task",
status: "to_do",
priority: 2,
assignee: "sigrid"
}get
Fetch a task by key.
Parameters
| Field | Type | Required |
|---|---|---|
taskKey | string | Yes |
plan
Get the linked plan for a task (if one exists). Plans come from the vmp planner.
Parameters
| Field | Type | Required | Notes |
|---|---|---|---|
taskId | string | Conditional | Task ULID. Required if taskKey is omitted. |
taskKey | string | Conditional | Alternative lookup. Required if taskId is omitted. |
get_prompt
Build the task-specific system prompt that agents receive when launched against this task. Includes description, acceptance criteria, linked requirements, and context.
Parameters
| Field | Type | Required |
|---|---|---|
taskKey | string | Yes |
This is useful for agents that want to see what an executor would receive before launching.
update
Update task fields. Pass only the fields you want to change.
Parameters
| Field | Type | Required |
|---|---|---|
taskKey | string | Yes |
description | string | No |
assignee | string | No |
reporter | string | No |
points | number | null | No |
priority | number | null | No |
metadata | object | No |
Use change_status to change status. Use pm_sprint.link_task to change sprint membership.
delete
Delete a task permanently. This action is reserved for intentional cleanup, not normal lifecycle movement. Fetch the task first with get and confirm the key, project, sprint, and checklist state before deleting it.
delete is permanent. Use it only after a confirming pm_task { action: "get" } shows you are removing the intended task. To move work through the lifecycle, use change_status instead.Parameters
| Field | Type | Required |
|---|---|---|
taskKey | string | Yes |
Example
pm_task { action: "get", taskKey: "MYAPI-42" }
pm_task { action: "delete", taskKey: "MYAPI-42" }search
Search tasks within a project.
Parameters
| Field | Type | Required | Notes |
|---|---|---|---|
projectKey | string | Yes | Scope to a specific project |
query | string | No | Search text |
status | string | No | Filter by status |
sprintId | string | No | Filter by sprint |
limit | number | No | Result cap |
Example
pm_task {
action: "search",
projectKey: "MYAPI",
status: "in_progress",
limit: 20
}change_status
Transition a task through the status lifecycle: backlog → to_do → in_progress → in_review → verified → done.
Parameters
| Field | Type | Required | Notes |
|---|---|---|---|
taskKey | string | Yes | |
to | string | Yes | Target status |
reason | string | No | Reason for the change |
Example
pm_task {
action: "change_status",
taskKey: "MYAPI-42",
to: "in_review",
reason: "Implementation complete, ready for code review"
}checklist_toggle
Toggle an individual checklist item on a task.
Parameters
| Field | Type | Required |
|---|---|---|
taskKey | string | Yes |
checklistId | string | Yes |
itemId | string | Yes |
checked | boolean | Yes |
checklist_lookup
Look up checklist names, items, or templates.
Parameters
| Field | Type | Required | Notes |
|---|---|---|---|
mode | string | No | names (default), items, or template |
query | string | No | Search query |
checklistName | string | Conditional | Required for template mode |
limit | number | No | Result cap |
Example
pm_task {
action: "checklist_lookup",
mode: "template",
checklistName: "code-review"
}event_list
Fetch the audit trail of events for a task — status changes, assignee changes, comments, session launches, and more.
Parameters
| Field | Type | Required | Notes |
|---|---|---|---|
taskKey | string | Yes | |
limit | number | No | Default 25, max 100 |
comment_create / comment_list / comment_delete
Manage task and task-review comments. Comments can be scoped to a review or assignment for threaded discussion.
comment_create
| Field | Type | Required | Notes |
|---|---|---|---|
taskKey | string | Yes | |
body | string | Yes | |
reviewId | string | No | Scope to a specific review |
assignmentId | string | No | Scope to a reviewer assignment |
parentCommentId | string | No | For threaded replies |
actorHandle | string | No | Who is commenting |
comment_list
| Field | Type | Required | Notes |
|---|---|---|---|
taskKey | string | Yes | |
reviewId | string | No | Filter by review |
assignmentId | string | No | Filter by assignment |
comment_delete
| Field | Type | Required | Notes |
|---|---|---|---|
taskKey | string | Yes | |
commentId | string | Yes | |
actorHandle | string | No | Who is deleting |
Deleting a comment also deletes its replies.
help
pm_task { action: "help" }help returns structured, read-only guidance that agents can inspect before calling task actions.
| Field | Contents |
|---|---|
actions | Current accepted action names, including delete, checklist_lookup, comment_delete, and help |
whenToUse | One-line guidance for core actions such as get, get_prompt, change_status, checklist_toggle, and comment_create |
examples | Representative calls, including fetching a task, moving it to review, and toggling a checklist item |
cautions | Guardrails such as fetch-before-update, fresh clientRequestId values, and using sprint link/unlink operations instead of task updates |
compatibility | Stability notes for the additive help payload and MCP error behavior |
Use this payload as the live reference when building agents that need to discover the task surface before mutating work.
Related
- pm_session — launch agent sessions against tasks
- pm_review — start reviews on completed tasks
- pm_sprint — link tasks to sprints