list_next_tasks
List the tasks you can start now: open, with nothing unfinished in the way, inside an active path of projects and groups, and either assigned to you or to nobody. Grouping directs execution: compare priority from the top-level group through each nested group to the task, at the first difference; a group comes before what it contains, and a task in several groups uses its highest active path. Ungrouped tasks use their own priority. Tasks on the same priority path are listed by ID for a stable order; ID is not a priority. Use value and size to choose among them; neither sorts the list. This starts nothing: read the chosen task with get, then call set_task_status with in_progress only when work actually starts.
- It
- Reads. It changes nothing.
- Who may call it
- Every user.
- Pages
- Answers in pages of at most 100, with a
continuationtoken for the next. - Answers with
- A list of tasks, each in short. Its fields. Not in it:
description,why,links,timeline,created_at,created_by,updated_atandunchanged_since.gethas those. - MCP tool
list_next_tasks- HTTP
POST /api/list-next-tasks- Command
vigile list-next-tasks
Input
| Field | Takes | What it is | |
|---|---|---|---|
project | string | optional | Only tasks inside this project, at any depth. |
parent | string | optional | Only tasks inside this task, at any depth: what can start now in one group. |
continuation | string | optional | The continuation token from the previous page. Return it unchanged to the same operation with the same filters; stop when no token is returned. |
A field that is not listed here is refused, as invalid_input. On the command line each field is an option, with hyphens for underscores: --project.
Example
The same call three ways, as agent1. It was made on the demo plan the pictures of this site show. Over HTTP and MCP, a call without a key acts as agent1 on a new instance.
Command line
vigile list-next-tasks --as agent1HTTP
curl -s http://127.0.0.1:8700/api/list-next-tasks \
-H 'content-type: application/json' \
-d '{}'MCP tool call
{
"name": "list_next_tasks",
"arguments": {}
}The answer
{
"tasks": [
{
"kind": "task",
"id": "WEB-005",
"title": "Total is wrong when a coupon is applied twice",
"type": "bug",
"status": "open",
"priority": 9,
"value": null,
"size": null,
"version": 1,
"contained_in": ["WEB", "WEB-001"],
"depends_on": [],
"assigned_to": [],
"is_assigned": false,
"is_next": true,
"is_waiting": false,
"waiting_for": [],
"has_problems": false,
"priority_path": [8, 9]
},
{
"kind": "task",
"id": "WEB-009",
"title": "Filters for price and category",
"type": "task",
"status": "open",
"priority": 0,
"value": null,
"size": null,
"version": 1,
"contained_in": ["WEB", "WEB-006"],
"depends_on": ["WEB-007"],
"assigned_to": [],
"is_assigned": false,
"is_next": true,
"is_waiting": false,
"waiting_for": [],
"has_problems": false,
"priority_path": [6, 0]
},
{
"kind": "task",
"id": "APP-016",
"title": "Home screen shows the latest orders",
"type": "task",
"status": "open",
"priority": 4,
"value": null,
"size": null,
"version": 1,
"contained_in": ["APP"],
"depends_on": [],
"assigned_to": [],
"is_assigned": false,
"is_next": true,
"is_waiting": false,
"waiting_for": [],
"has_problems": false,
"priority_path": [4]
}
]
}
This is what a service answered when this page was built. Over HTTP it is the body of the response, over MCP the text of the tool result, and the command line prints it in words unless given --json.
What it answers
tasks: the tasks the caller can start now, each in short. A continuation token is there when more follow.
Rules
- A task is listed when it is open, nothing unfinished is in front of it, at least one path through its projects and groups is active, and it is assigned to the caller or to nobody.
- Grouping directs execution. Priority is compared from the outermost group through each nested group to the task, at the first difference; an open group comes before what it contains. A task in several groups uses its highest active path, and an ungrouped task uses its own priority.
- Each task carries the
priority_paththat placed it. Tasks on the same path are listed by ID, which keeps the order stable and says nothing of importance: choose among them usingvalueandsize. - Drafts are never listed.
projectandparentkeep the list inside one project or one group, at any depth.- The answer depends on who asks: a task assigned to someone else is not in it. A continuation token does not pass from one user to another.
- Listing starts nothing. Take a task with
set_task_statusandin_progress.
Errors
not_found: the project or the parent does not exist.invalid_input: a continuation token that is not valid, or belongs to another list or to another user: this list is the caller's own.
See also
Next and waiting explains how it is worked out.