MCP Task Orchestrator · Field guidePlate 7 of 10
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 which seat owes each, as missingBySeat), and the key of the guidance and skill for the next one. When it cannot advance it adds blockedBy. Any decisions raised on the item are listed too, in every status except withdrawn. |
| 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 blocked item with its blockers, the role each must reach and whether that is satisfied. An explicitly blocked item also carries its reason, the decisionId it waits on and whether it is resumable. For one item, the context 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. Three modes: no id for the whole database, itemId for one item, anchorId to list an item's children with subtree counts. |
| 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. Remaining ties go to the lower id. oldest gives fair first-in, first-out draining.
Items whose blockers have not reached their threshold, items with an active claim, and items under an ancestor with an active claim (the caller's own claims included in both cases). Items with no lifecycle never appear, and complexityMax also drops items with no complexity set. includeClaimed lifts the two claim filters for operators and adds isClaimed to every row, true only for the item's own active claim. An empty page says why in data.reason, claim_held or dependency_unmet, and gives no reason when nothing matched at all.
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. |
description, statusLabel | Free text, both optional | A long description, and a free-form label for the item's status. |
type | One schema key, such as bug-fix. Required on create | Selects the schema, so the gates and the lifecycle mode. A missing type is invalid_request and a blank one is schema_violation. When the root declares types, an undeclared one is a schema_violation that lists the availableTypes. |
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. |
properties | A JSON object, optional | Free-form data on the item. It cannot carry a traits key. |
schemaVersion | {server, root, key, layer}, read-only | The schema pin: the config versions and base schema the item resolves through. It is taken on create and moves on a type or trait change, a move to another root, a reopen from terminal, or items_write repin. |
requiresVerification, metadata | A boolean; free-form text | Whether completion needs verification, and free-form metadata text. |
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.
A list answers {items, page: {total, truncated, next?, capped?}}. next is present exactly when truncated is true. capped means the underlying list was cut at a fixed ceiling, so total is the capped size. Pass page.next back as cursor. There is no offset.
The orchestration profile has every select. The knowledge profile has get, list, overview, related, schema and search: no context, next, blocked or history. The director profile has get, list, overview and blocked, plus deps_read list and graph.
related finds items by dependency, link, shared tag and similar text and says why in reasons. docs_read reads plan documents, deps_read walks incoming links and the graph, and get takes fields or ifVersion to stay small.
project. Its id is the rootId that per-project config, plan documents and rules are stored under. Project-scoped improvement proposals live in a container under their project root; the process-wide container holds the rest./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.