MCP Task Orchestrator · Field guidePlate 7 of 9
Agents read state far more often than they change it. A handful of read calls answer the questions a session actually has: where was I, what is next, why is this stuck, and what does this item need.
| The question | The call | What comes back |
|---|---|---|
| Where did we leave off? | items_read(select="history", since="…") items_read(select="context") | Recent transitions, newest first, with their actors when the caller may see attribution, and the active and stalled items. |
| Is anything unhealthy? | items_read(select="context") | Active, blocked and stalled items, plus a count of live and expired claims. |
| What does this item need? | items_read(select="context", itemId="a3f2c91e") | Its gate status: which required notes exist, which are missing, and the key of the guidance and skill for the next one. |
| What should I pick up? | items_read(select="next") | Ranked items that can start right now. |
| Why can't this start? | items_read(select="blocked") items_read(select="context", itemId) | Each blocker, the role it must reach, and whether that is satisfied. For one item, the gate status says whether it can advance and which gate fails first. |
| What is under this feature? | items_read(select="overview", itemId) | The item, its direct children, and a count of children per role. |
| Have we seen this before? | items_read(select="search", query="…") | Relevance-ranked hits with snippets, across item content, note bodies and documents. |
| What must this note contain? | items_read(select="schema", itemId, fields=["guidance"]) | The resolved schema with the description, skill and (with fields) guidance text of every note. |
An item is stalled when it is in work or review and a required note for its current phase is still missing.
A sample backlog, listed oldest first. Change the call and watch which items qualify and in what order.
| Rank | Item | Priority | Complexity | Outcome |
|---|
By default: high, then medium, then low priority. Within a priority, lowest complexity first, with unset complexity last. oldest gives fair first-in, first-out draining.
Items whose blockers have not reached their threshold, items another agent has claimed, and items under a claimed ancestor. includeClaimed lifts the two claim filters for operators.
The default role is queue. A review fleet asks with role="review", a triage agent with role="blocked".
| Field | Values | What it drives |
|---|---|---|
title, summary | Up to 500 and 2000 characters | What agents see in lists and search. |
type | One schema key, such as bug-fix | Selects the schema, so the gates and the lifecycle mode. |
tags | A list, lowercase with hyphens | Filtering. Tags never select a schema. |
priority | high, medium (default), low | First key of the next-item ranking. |
complexity | 1 to 10, optional | Second key of the ranking, and the complexityMax filter. |
traits | A list of trait names | Extra notes, seats, resources and dispatch for this one item. |
parentId | An item id, or none for a root | The hierarchy. Depth is computed and has no fixed limit. |
The role is not among them: it only changes through advance. Ids accept a full UUID or a prefix of 8 to 32 hex characters. An ambiguous prefix is an error. The server never guesses.
One overview call returns a feature, its children and per-role counts. That replaces a get per item plus their notes when all you need is status.
notes_read list returns notes without bodies and gives each body's length. Fetch a body only for the note you will read, filtered by role.
Full-text search runs a substring index and a word-stem index and fuses the two rankings. Several words mean all of them. Scope it to a subtree, a role or tags.
project. Its id is the rootId that per-project config, plan documents and rules are stored under./task-orchestrator:init finds or creates the project root, writes project: { rootId, name } into the repo's .taskorchestrator/config.yaml, pushes the config and seeds the bundled rules.
init --user creates one root for every directory that has no config of its own. It gives new items a home. It does not narrow what reads return.
With a project root, agents pass ancestorId on the items_read selects list, search, next, context and blocked, and parent new top-level items under the root.