| name | taskgraph-inspect-work |
| description | Inspect Taskgraph items, hierarchy, dependencies, readiness, blockers, context, and change history through the MCP. Use when an agent needs to find work, understand status, diagnose why work is blocked, review recent changes, or prepare execution context. |
Taskgraph Inspect Work
Use read tools first to build a bounded view of Taskgraph state. Resolve references, inspect the item, then widen to context, graph, blockers, or changes only as needed.
Choose the smallest read
tg_resolve: turn an ID, canonical path, or alias into one item. Stop on AMBIGUOUS_REFERENCE or NOT_FOUND.tg_get_item: get one item plus bounded ancestors, children, and dependencies as returned by the current server.tg_search_items: find items by a text query. Set limit no higher than needed; the server caps it at 200.tg_get_graph: inspect hierarchy and the direct dependency neighborhood. Set max_items; the server caps it at 500.tg_context_bundle: prepare deterministic context for one item. Pass ref directly, or use source: {"item": ...}.tg_explain_blocked: return readiness reasons for one item.tg_list_changes: inspect audit changes after a known revision with after_revision and a bounded limit.
Do not request a whole workspace when a path, project, or item is enough. Preserve IDs, canonical paths, versions, and revisions in your notes.
Inspect an item
- Resolve the user reference.
- Call
tg_get_item with the stable ID or canonical path.
- If the item is part of a plan, call
tg_get_graph with a small max_items to see ancestors, children, and nearby relationships.
- If an agent will act on it, call
tg_context_bundle and keep within the requested context budget when the server supports one.
The current implementation returns item data with fields such as status, effective_state, execution_mode, child_gate, completion_policy, priority, version, last_revision, and canonical path. Use those fields to explain what the system knows; do not infer missing fields.
Explain readiness or blockage
Call tg_explain_blocked for the item. Read every returned reason. Common codes include:
NOT_EXECUTABLE: the item is a container, not an action.STATUS_NOT_OPEN: the stored status is not open.ARCHIVED or ARCHIVED_ANCESTOR: the item is hidden from normal work.ANCESTOR_STATUS: a parent gate is closed.NOT_BEFORE: the start time has not passed.ACTIVE_CLAIM: another active claim exists.ASSIGNED_TO_OTHER: the item belongs to another actor.MISSING_CAPABILITY: the MCP session lacks a required capability.AGENT_CLAIM_LIMIT: the session already holds its claim limit.INCOMPLETE_CHILDREN: a child gate is not satisfied.UNSATISFIED_DEPENDENCY: a hard blocker is not done or skipped.MANUAL_BLOCKER: a manual blocker remains unresolved.
For a dependency issue, inspect the BlockingItem or the nearby graph. Explain the direction as “A blocks B” so the action is clear: finish or skip A, waive or remove the relationship only with user authority, or change the plan.
Inspect recent changes
Use tg_list_changes only when the caller has a revision or wants a recent audit view. Start with a small limit. Use the returned revision range to avoid rereading the same changes.
Compare the change record with a fresh tg_get_item before claiming that a field changed. A revision is workspace-wide; an item version controls safe item patches.
Keep inspection read-only
- Do not patch, create, claim, release, waive, or report work during an inspection unless the user asks for that change.
- Do not expose claim tokens or treat them as ordinary item data.
- If a read fails, show the MCP error code and the next safe read to try. Do not replace a missing result with a guess.
- Keep graph and search results bounded. State when the returned result is truncated or limited.
- The current server publishes an empty input schema for
tg_list_changes even though the handler accepts after_revision and limit. If a strict client rejects those arguments, report a schema compatibility issue and stop.
