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.\n\n### Parameters\n\n| Field | Type | Required |\n|-------|------|----------|\n| `taskKey` | string | Yes |\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## 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.
Parameters
| Field | Type | Required |
|---|---|---|
taskKey | string | Yes |
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" }Related
- pm_session — launch agent sessions against tasks
- pm_review — start reviews on completed tasks
- pm_sprint — link tasks to sprints