Skip to main content
Glama
SamiulH25

Pi Conductor

by SamiulH25
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

pi_spawn

Start a background Pi worker for a self-contained task and return its id at once. Use pi_wait or pi_digest to read compact results and judge them.

Instructions

Start a Pi worker in the background on a self-contained task and return its id at once. Workers always use the model the user set with pi_model (not selectable here). Give it a complete standalone brief (it has no access to this conversation). Use disjoint dirs or let worktree isolation separate parallel workers. Then use pi_wait / pi_digest to read compact results and judge them. Workers are long-lived RPC processes that keep their context: for a fix or a follow-up in the same area, pi_send an existing worker instead of spawning a new one.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
dirNoWorking directory (default: session cwd)
taskYesComplete standalone instructions for the worker
agentNoAgent type (default general). general: unrestricted, short SUMMARY (the pre-agent-types behaviour); dev: implements changes: read, edit, write, shell; short SUMMARY of what changed. Worktree by default; explore: read-only investigator: finds and reads code, returns a long evidence-backed FINDINGS report (never summarized). No worktree; review: read-only reviewer: returns every issue found with file:line, severity and a fix (never summarized). No worktree
titleNoShort label
checksNoToolbox checks (pi_tools) the worker must run and pass after its last edit. Default: the toolbox entries marked required. [] = none for this task. The worker runs them itself with `check <name>`; serial ones never run twice at once.
effortNoReasoning effort for this worker only (default: the pi_effort setting). Raise it for tasks that need real reasoning.
expectNoPaths (relative to dir) the task must change. If the worker finishes without changing one, the digest, status and wake-up message carry a warning.
noDictNoSkip the project-dictionary requirement for a dev/general worker (the first one in a project is refused until pi_dict has entries).
verifyNoA shell command the PLUGIN runs itself in the worker's directory after the worker finishes (one at a time across workers, up to 10 min). Prefer toolbox checks (pi_tools), which the worker runs and fixes itself; use verify for a final gate the worker must not run. The result goes in the digest; a failure counts as a warning.
worktreeNoIsolate in a new git worktree (default depends on agent type; dev and general: true when dir is a git repo, explore and review: false)
fixRoundsNoWith verify: how many times (0-3, default 0) a failing verify is sent back to the worker to fix automatically.
maxMinutesNotime limit for the run (default depends on agent type, 15-20). At 85% the worker is told to wrap up; at 100% it is asked for a partial report and gets 2 more minutes before it is stopped. pi_send can resume it.
verifyTimeoutSecNoTime limit for the verify command (default 300, max 600).

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.1.0

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does well: it discloses the async/non-blocking nature (returns id at once), that the model is fixed by the pi_model setting and not selectable, that workers have no access to this conversation, and that they are long-lived RPC processes that retain context. It does not discuss failure/timeout behavior (covered only in schema descriptions) or concurrency limits, keeping it short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Six sentences, each carrying distinct information: what it does, the model constraint, the standalone-brief requirement, isolation guidance, result-reading path, and the pi_send alternative. The core action and return value are front-loaded, and there is no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 13-parameter tool with no output schema and no annotations, the description covers the whole lifecycle an agent needs: spawning semantics, isolation, model binding, follow-up routing, and result inspection, while the rich schema descriptions handle per-parameter detail. Nothing essential to a correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3; the description adds genuine meaning beyond the schema by explaining that the task brief must be fully standalone because the worker cannot see this conversation, and by noting the model is not a parameter here. That said, the per-parameter semantics (checks vs verify, effort, maxMinutes) live almost entirely in the schema, not the description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Start a Pi worker') plus the scope ('in the background on a self-contained task') and the immediate return value ('return its id at once'). It explicitly distinguishes itself from pi_send (for follow-ups), pi_wait/pi_digest (for reading results), so an agent can route correctly without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use and when-not-to-use guidance: use pi_send for a fix or follow-up in the same area instead of spawning a new worker, use disjoint dirs or worktree isolation for parallel workers, and use pi_wait/pi_digest to judge results. Alternatives are named with the condition that selects them.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools