plumb

Official

Overview Schema Source Related Servers Discussions Admin

run_task

Execute a stored per-language task command—build, lint, test, e2e, or verify—without a shell. Runs only the saved command for your workspace's language or one you name.

Instructions

Run a stored per-language task command — build, lint, test, e2e, verify, or a project-defined slot — configured in [tasks.]. It executes only the command the user saved (no shell, no agent-supplied command line), for this workspace's primary language or the one you name in language. Runs from the workspace root or [tasks.] working_dir, with its env. A project-supplied (.plumb/config.toml) command must be trusted first (run plumb trust); the shipped defaults and global-config commands always run. Output and runtime are bounded. Pairs with topology_affected (which says WHICH tests to run; this runs them).

Input Schema

TableJSON Schema

Name	Required	Description
`run`	No	Optional test-name filter for the {run} placeholder (go -run, pytest -k), e.g. TestA\|TestB. Letters, digits, space, ._/:@\|^$*+?()[]-; no leading - or space.
`slot`	No	Which stored task command to run: build, lint, test, e2e, verify, or a project-defined slot under [tasks.<lang>]. session_start lists what's configured; an unconfigured slot is refused with that list.
`target`	No	Optional value for the {target} placeholder, e.g. a package. One shell-safe argument ([A-Za-z0-9._/:@-]); refused if the command has none.
`verbose`	No	Fill the {verbose:<flag>} placeholder (go/pytest -v), e.g. to see skipped tests.
`language`	No	Which [tasks.<language>] block to run, in a polyglot repo. Omit for the primary. A language with no commands is refused, naming those that have them.

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv0.21.0Oct 2, 2026

changedInput schema / properties / language / description

Previous value: -"Which [tasks.<language>] block to run, for a polyglot repo whose other languages are not the primary. Omit for the primary. A language with no commands is refused, naming those that have them."New value: +"Which [tasks.<language>] block to run, in a polyglot repo. Omit for the primary. A language with no commands is refused, naming those that have them."

addedInput schema / properties / run

Added value: +{
+  "description": "Optional test-name filter for the {run} placeholder (go -run, pytest -k), e.g. TestA|TestB. Letters, digits, space, ._/:@|^$*+?()[]-; no leading - or space.",
+  "type": "string"
+}

changedInput schema / properties / target / description

Previous value: -"Optional target substituted for a {target} token in the stored command (e.g. one test name or package). Restricted to one shell-safe argument ([A-Za-z0-9._/:@-]); refused if the command has no {target} slot."New value: +"Optional value for the {target} placeholder, e.g. a package. One shell-safe argument ([A-Za-z0-9._/:@-]); refused if the command has none."

addedInput schema / properties / verbose

Added value: +{
+  "description": "Fill the {verbose:<flag>} placeholder (go/pytest -v), e.g. to see skipped tests.",
+  "type": "boolean"
+}

Changed2 schema fields changedv0.18.0Sep 6, 2026

addedInput schema / properties / language

Added value: +{
+  "description": "Which [tasks.<language>] block to run, for a polyglot repo whose other languages are not the primary. Omit for the primary. A language with no commands is refused, naming those that have them.",
+  "type": "string"
+}

changedInput schema / properties / target / description

Previous value: -"Optional target substituted for a {target} token in the stored command (e.g. a single test name or package). The shipped go/python/rust test defaults carry a defaulted placeholder ({target:./...}), so scoping works with no config edit and omitting the target still runs everything. Restricted to one shell-safe argument ([A-Za-z0-9._/:@-]); refused if the command has no {target} slot."New value: +"Optional target substituted for a {target} token in the stored command (e.g. one test name or package). Restricted to one shell-safe argument ([A-Za-z0-9._/:@-]); refused if the command has no {target} slot."

Changed1 schema field changedv0.17.7Aug 29, 2026

changedInput schema / properties / target / description

Previous value: -"Optional target substituted for a {target} token in the stored command (e.g. a single test name or package). The shipped go/python/rust test defaults carry a defaulted placeholder ({target:./...}), so scoping works with no config edit and omitting the target still runs everything. Restricted to one shell-safe argument ([A-Za-z0-9._/:@-]); refused if the stored command has no {target}."New value: +"Optional target substituted for a {target} token in the stored command (e.g. a single test name or package). The shipped go/python/rust test defaults carry a defaulted placeholder ({target:./...}), so scoping works with no config edit and omitting the target still runs everything. Restricted to one shell-safe argument ([A-Za-z0-9._/:@-]); refused if the command has no {target} slot."

Changed2 schema fields changedv0.17.2Aug 22, 2026

changedInput schema / properties / slot / description

Previous value: -"Which stored task command to run: build, lint, test, e2e (integration), or verify (build then test). The command is configured per language in [tasks.<lang>] and resolved for this workspace's language — you cannot pass an arbitrary command."New value: +"Which stored task command to run: build, lint, test, e2e, verify, or a project-defined slot under [tasks.<lang>]. session_start lists what's configured; an unconfigured slot is refused with that list."

removedInput schema / properties / slot / enum

Removed value: -[
-  "build",
-  "lint",
-  "test",
-  "e2e",
-  "verify"
-]

Changed1 schema field changedv0.17.0Aug 22, 2026

changedInput schema / properties / target / description

Previous value: -"Optional target substituted for a literal {target} token in the stored command (e.g. a single test name or package). Restricted to one shell-safe argument ([A-Za-z0-9._/:@-]); refused if the stored command has no {target}."New value: +"Optional target substituted for a {target} token in the stored command (e.g. a single test name or package). The shipped go/python/rust test defaults carry a defaulted placeholder ({target:./...}), so scoping works with no config edit and omitting the target still runs everything. Restricted to one shell-safe argument ([A-Za-z0-9._/:@-]); refused if the stored command has no {target}."

First observedv0.16.6Aug 17, 2026

TDQS

A4.4/5.0

Behavior5/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 so well: it discloses the execution model (stored command only, no shell, no agent-supplied command line), the trust/gating model for project-supplied vs shipped vs global-config commands, the env/working_dir inheritance, and that output and runtime are bounded.

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

Conciseness4/5

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

Front-loaded with the core action and a dense, information-rich paragraph; nearly every clause adds a distinct constraint (scope, trust, cwd/env, bounds, pair tool). It is long, but the length is largely earned by real behavioral content.

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 task-runner with no output schema and five optional parameters, the description supplies the operational context an agent needs: where commands come from, the trust gate, language selection, working directory/env, and output bounds. Nothing essential to correct invocation appears missing.

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

Parameters3/5

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

Schema description coverage is 100%, so each parameter (run, slot, target, verbose, language) is already fully documented in the schema. The description restates the slot list and language concept but adds no syntax or placeholder detail beyond what the schema already provides, so the baseline 3 applies.

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 (Run) and resource (a stored per-language task command) plus the exact enumerated slots and where they come from ([tasks.<lang>]). It also disambiguates from the sibling run_command by stressing it executes only the saved command, with no shell or agent-supplied command line.

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

Usage Guidelines4/5

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

Gives clear context (workspace root or working_dir, primary language or the one named in `language`) and an explicit prerequisite: project-supplied commands must be trusted first via `plumb trust`, while shipped defaults run unconditionally. It names topology_affected and its complementary role, but never states when to prefer run_command instead for arbitrary commands.

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

Deploy Server

run_task

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools