Vigile
SearchContents

DocumentationOperations

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.

The operation's own description: what an agent reads to decide whether and how to call it.
It
Reads. It changes nothing.
Who may call it
Every user.
Pages
Answers in pages of at most 100, with a continuation token 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_at and unchanged_since. get has those.
MCP tool
list_next_tasks
HTTP
POST /api/list-next-tasks
Command
vigile list-next-tasks

Input

FieldTakesWhat it is
projectstringoptionalOnly tasks inside this project, at any depth.
parentstringoptionalOnly tasks inside this task, at any depth: what can start now in one group.
continuationstringoptionalThe 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 agent1

HTTP

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_path that placed it. Tasks on the same path are listed by ID, which keeps the order stable and says nothing of importance: choose among them using value and size.
  • Drafts are never listed.
  • project and parent keep 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_status and in_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.