Loading ToolBench
MCP server for Stageflow pipeline runtime, providing tools for pipeline catalog browsing, run management, stage control, and operator interaction
27 tools with explicit schemas and descriptions. Naming is verb-forward and clear (list_, get_, start_, run_, answer_, decide_, etc.). Descriptions are detailed and contextual (avg ~150 chars), explaining WHAT, WHEN, and prerequisites. Schemas use proper JSON Schema with types, enums, and constraints. However, some parameter descriptions lack actionable format guidance (e.g., 'ISO date string' without pattern), and output schemas are not documented in tool definitions. Error handling is mentioned in descriptions but not formalized in schema. Tool composition is strong, tools chain well (e.g., start_run → wait_run → answer_gate → wait_run). Security-sensitive tools (answer_gate, recover_manual_stage) lack explicit permission declarations.
Deliver an AskOperatorAnswer for a stage in waiting_for_input (same semantics as POST /api/runs/:id/stages/:stageId/answer). Pass answer as { promptId, kind, ... } matching the pending prompt.
Ask the operator a question and stop. Supports multiple prompt kinds. Calling this tool immediately ends your turn — after it returns, do not call any more tools and do not keep talking; you will be resumed in a new turn once the operator has answered. Does not complete the stage — call emit_stage_envelope when finished.
Resolve a feedback-loop wait_for_human decision (extend, continue, or abandon). Same semantics as POST /api/runs/:id/stages/:stageId/feedback-decision.
Describe a pipeline by path or id: metadata, stages, DAG edges, and io schemas. Does not run anything.
Emit a stage completion envelope (status, summary, artifacts, payload, fork_choice, checklist_attestations). Required to complete a stage. Validates against the stage's declared output schema and fork/clone routing.
Output schemas not documented in tool definitions. LLMs cannot plan downstream calls or extract required fields without knowing response structure.
Parameter format constraints lack actionable guidance. 'ISO date string' and 'Filesystem path' appear in descriptions but lack regex patterns or examples of valid formats.
Destructive/sensitive tools (answer_gate, recover_manual_stage, stop_manual_recovery, decide_feedback_loop) lack explicit permission declarations or scope requirements.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 67 | 2026-07-28+ | v2 |
Server health and soft-max run capacity: activeRunIds, activeCount, maxConcurrent, slotsAvailable, version. Start until slotsAvailable is 0; then wait for a run to finish or raise STAGEFLOW_MAX_CONCURRENT_RUNS.
Fetch a run by id: metadata, stages, and their status/summary/payload/artifacts. Stages are ordered by execution (topological sort of the DAG). Artifacts are file metadata only (use read_artifact for content).
Read every execution attempt for a stage, including durable completion-check results and their evidence. Use this to understand an automatic repair or a failed verification.
Lightweight count and identity of stages waiting for operator input — no pending_prompt, waiting_artifacts, or waiting_questions (use list_waiting for full detail). Optional runId scopes to one run; optional path scopes to one project (derived via findProjectRoot, same rule as elsewhere); omitting both spans every project the store knows about.
List catalog model ids from the project catalog (same source as GET /api/models)
List manifest-declared pipeline paths across every project this host knows about (this host's own project plus any project a run has ever been recorded for). Each entry is tagged with project_root. A project with no runs yet won't appear until its first run exists.
List git-root .mcp.json servers as names and transport only (same as GET /api/project-mcp). Inspect is not attach; it does not interpolate, spawn, or change stage MCP.
List login-capable model providers with auth readiness and a Pi-home detect summary. Read-only; does not log in or return secrets.
List known pipeline runs. Optional filters: status, since (ISO created_at lower bound), pipeline (id or path).
List persisted stage log events for a run stage (optional attempt filter). Prefer over bloating get_run.
List manifest-declared task paths across every project this host knows about (this host's own project plus any project a run has ever been recorded for). Each entry is tagged with project_root. A project with no runs yet won't appear until its first run exists.
List stages waiting for operator input across runs (optional runId filter). Includes pending_prompt and waiting_* fields per gate.
Probe one named git-root .mcp.json server with connect-and-exit (same as POST /api/project-mcp/:name/probe). Inspect is not attach; YAML mcp: still allowlists what a stage receives.
Read a run stage artifact by path: returns content (text or base64 image). Artifacts are files written by emit_stage_envelope or write_stage_artifact.
Explicitly approve one fresh attempt for a manual-recovery stage after a completion verification failure. Optional guidance is recorded and supplied to the agent with the failed-check evidence.
Run a single stage (not a full pipeline) with optional envelope_ref input resolution, task/task_path, optional model override, and optional blocking wait. Returns { runId } immediately or { runId, run } when blocking=true.
Start a pipeline run using a filesystem pipeline path or an inline pipeline definition ({ id, stages: [...] }, each stage the same shape as a YAML stage body — no uses: refs), and either task_path (catalog task file) or an inline task object. Returns { runId }. On conflict returns isError with code busy_capacity (soft max full) or busy_checkout (same checkout leased), plus activeCount/maxConcurrent.
Record the operator's decision to leave a manual-recovery stage failed. This is terminal for that stage; start a fresh run to try again later.
Poll for new live assistant text a running (or recently finished) stage attempt has produced, since a byte-offset cursor. Separate from list_stage_events — no prompt/artifact/question detail, just the raw redacted text as it streamed. Omit since_offset to catch up on everything currently retained.
Validate the project catalog (pipelines, tasks, stages, schemas) and return findings (errors, warnings, infos). Does not run anything.
Long-poll until a run is waiting for HITL input and/or terminal (succeeded/failed), or until timeout_ms. Default until=any wakes on waiting OR terminal. Abort cancels only this wait (not the run). Optional notifications/progress when the client supplies _meta.progressToken. Compose: wait_run → answer_gate → wait_run.
Write a stage artifact (file) to the run workspace. Path is relative to the run's artifact directory. Content is UTF-8 text.
Error handling guidance is narrative in descriptions but not formalized. No structured error codes, recovery hints, or categorization (retryable vs fatal) in schema.
Complex parameter types (envelope_ref as object|array, stage as string|object) lack clear disambiguation. LLMs may struggle to choose between inline vs reference forms.