par5-mcp is an MCP server for parallel batch processing across lists of items using shell commands and AI agents.
List Management:
Create (create_list): Define a named list of items (file paths, URLs, identifiers, etc.)
Create from shell output (create_list_from_shell): Populate a list by running a shell command (e.g., find, git ls-files) and parsing its newline-delimited output
Get (get_list), Update (update_list), Delete (delete_list), List all (list_all_lists): Full CRUD and inspection of lists within a session
Parallel Execution:
Shell commands (run_shell_across_list): Run a shell command for every item in a list in parallel (batches of 10), using $item as a placeholder; stdout/stderr streamed to separate per-item files
AI agents (run_agent_across_list): Spawn AI coding agents (Claude, Gemini, Codex, or OpenCode) for every item in parallel (batches of 10), using {{item}} in prompts; agents run autonomously with auto-permission flags and streamed output
Configuration: Customize batch size, agent arguments, and disable specific agents via environment variables.
Spawns Gemini coding agents in parallel to process lists of items, with each agent executing custom prompts that can include item-specific context for batch AI-powered code processing and analysis.
Spawns Codex coding agents in parallel to process lists of items, with each agent executing custom prompts that can include item-specific context for batch AI-powered code processing and analysis.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@par5-mcp run shell command 'wc -l $item' across all files in list 'abc-123'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP (Model Context Protocol) server that runs shell commands and AI coding agents across lists of items in parallel. Use it to process files in batches, run linters across targets, or delegate work to multiple agents.
List Management: Create, update, delete, and inspect lists of items such as file paths, URLs, and identifiers
Parallel Shell Execution: Run shell commands across all items in a list with batched parallelism
Multi-Agent Orchestration: Spawn Claude, Gemini, or Codex agents in parallel to process items
Streaming Output: Results stream to files in real-time for monitoring progress
Batched Processing: Commands and agents run in batches of 10 to avoid overwhelming the system
Related MCP server: Claude Parallel Tasks MCP Server
npm install par5-mcpOr install globally:
npm install -g par5-mcpAdd to your MCP client configuration:
{
"mcpServers": {
"par5": {
"command": "npx",
"args": ["par5-mcp"]
}
}
}Or if installed globally:
{
"mcpServers": {
"par5": {
"command": "par5-mcp"
}
}
}create_listCreates a named list of items for parallel processing.
Parameters:
items (string[]): Array of items to store in the list
Returns: A unique list ID to use with other tools
Example:
create_list(items: ["src/a.ts", "src/b.ts", "src/c.ts"])
// Returns: list_id = "abc-123-..."get_listRetrieves the items in an existing list by its ID.
Parameters:
list_id (string): The list ID returned by create_list
update_listUpdates an existing list by replacing its items with a new array.
Parameters:
list_id (string): The list ID to update
items (string[]): The new array of items
delete_listDeletes an existing list by its ID.
Parameters:
list_id (string): The list ID to delete
list_all_listsLists all existing lists and their item counts.
Parameters: None
run_shell_across_listExecutes a shell command for each item in a list. Commands run in batches of 10 parallel processes.
Parameters:
list_id (string): The list ID to iterate over
command (string): Shell command with $item placeholder
Variable Substitution:
Use $item in your command. It will be replaced with each list item and
shell-escaped.
Example:
run_shell_across_list(
list_id: "abc-123",
command: "wc -l $item"
)This runs wc -l 'src/a.ts', wc -l 'src/b.ts', etc. in parallel.
Output:
Standard output and standard error are streamed to separate files per item
File paths are returned for you to read the results
run_agent_across_listSpawns an AI coding agent for each item in a list. Agents run in batches of 10 with a 5-minute timeout per agent.
Parameters:
list_id (string): The list ID to iterate over
agent (enum): "claude", "gemini", or "codex"
prompt (string): Prompt with {{item}} placeholder
Available Agents:
Agent | CLI | Auto-Accept Flag |
| Claude Code CLI |
|
| Google Gemini CLI |
|
| OpenAI Codex CLI |
|
Variable Substitution:
Use {{item}} in your prompt - it will be replaced with each list item
Example:
run_agent_across_list(
list_id: "abc-123",
agent: "claude",
prompt: "Review {{item}} for security vulnerabilities and suggest fixes"
)Output:
Standard output and standard error are streamed to separate files per item
File paths are returned for you to read the agent outputs
Here's a typical workflow for processing multiple files:
Create a list of files to process:
create_list(items: ["src/auth.ts", "src/api.ts", "src/utils.ts"])Run a shell command across all files:
run_shell_across_list(
list_id: "<returned-id>",
command: "cat $item | grep -n 'TODO'"
)Or delegate to AI agents:
run_agent_across_list(
list_id: "<returned-id>",
agent: "claude",
prompt: "Add comprehensive JSDoc comments to all exported functions in {{item}}"
)Read the output files to check results
Clean up:
delete_list(list_id: "<returned-id>")The following environment variables can be used to configure par5-mcp:
Variable | Description | Default |
| Number of parallel processes per batch |
|
| Additional arguments passed to all agents | (none) |
| Additional arguments passed to Claude CLI | (none) |
| Additional arguments passed to Gemini CLI | (none) |
| Additional arguments passed to Codex CLI | (none) |
| Set to any value to disable the Claude agent | (none) |
| Set to any value to disable the Gemini agent | (none) |
| Set to any value to disable the Codex agent | (none) |
Example:
{
"mcpServers": {
"par5": {
"command": "npx",
"args": ["par5-mcp"],
"env": {
"PAR5_BATCH_SIZE": "20",
"PAR5_CLAUDE_ARGS": "--model claude-sonnet-4-20250514"
}
}
}
}Results are written to temporary files in the system temp directory under par5-mcp-results/:
/tmp/par5-mcp-results/<run-id>/
├── auth.ts.stdout.txt
├── auth.ts.stderr.txt
├── api.ts.stdout.txt
├── api.ts.stderr.txt
└── ...File names are derived from the item value (sanitized for filesystem safety).
Please start a Discussion before proposing a change. If we accept the proposal, a Mathematic maintainer or AI agent will implement it and open a pull request. We will link that pull request to the Discussion and credit the proposal's original author. GitHub restricts pull request creation to Mathematic maintainers, repository collaborators with write, maintain, or admin access, and authorized maintenance agents. See CONTRIBUTING.md for the full process.
git clone https://github.com/mathematic-inc/par5-mcp.git
cd par5-mcp
mise install
mise exec -- pnpm install --frozen-lockfile
mise exec -- hk install
mise exec -- pnpm buildmise exec -- pnpm startNode.js 20+
For run_agent_across_list:
claude agent requires Claude Code CLI installed
gemini agent requires Gemini CLI installed
codex agent requires Codex CLI installed
Apache-2.0
This project is free and open-source work by a 501(c)(3) non-profit. If you find it useful, please consider donating.
Creates a named list of items for parallel processing. Use this tool when you need to perform the same operation across multiple files, URLs, or any collection of items.
WHEN TO USE:
Before running shell commands or AI agents across multiple items
When you have a collection of file paths, URLs, identifiers, or any strings to process in parallel
WORKFLOW:
Call create_list with your array of items
Use the returned list_id with run_shell_across_list or run_agent_across_list
The list persists for the duration of the session
EXAMPLE: To process files ["src/a.ts", "src/b.ts", "src/c.ts"], first create a list, then use run_shell_across_list or run_agent_across_list with the returned id.
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | Array of items to store in the list. Each item can be a file path, URL, identifier, or any string that will be substituted into commands or prompts. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the full burden. It states that the list persists for the session duration and returns a list_id, but does not disclose potential side effects, idempotency, maximum list size, or error conditions. This is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with clear sections (WHEN TO USE, WORKFLOW, EXAMPLE). Every sentence contributes meaningful information, and the most important purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 param, no output schema, no annotations), the description covers the purpose, usage guidelines, and workflow with an example. However, it does not explicitly describe the return value structure (e.g., list_id), though it is implied in the workflow. Slightly incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with a description for the 'items' parameter. The description adds value by explaining that each item can be a file path, URL, identifier, or any string for substitution in commands, which goes beyond the schema description. Could be more precise about constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Creates a named list of items for parallel processing', indicating the verb and resource. However, it mentions a 'named list' but the input schema only has an 'items' parameter, not a name. It distinguishes from siblings like create_list_from_shell by stating it takes an array of items, but could be more explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a 'WHEN TO USE' section specifying usage before running shell commands or AI agents across multiple items, and a 'WORKFLOW' with clear steps. It references sibling tools (run_shell_across_list, run_agent_across_list) as subsequent steps, providing excellent guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates a list by running a shell command and parsing its newline-delimited output.
WHEN TO USE:
When you need to create a list from command output (e.g., find, ls, grep, git ls-files)
When the list of items to process is determined by a shell command
As an alternative to manually specifying items in create_list
EXAMPLES:
"find src -name '*.ts'" to get all TypeScript files
"git ls-files '*.tsx'" to get all tracked TSX files
"ls *.json" to get all JSON files in current directory
"grep -l 'TODO' src/**/*.ts" to get files containing TODO
WORKFLOW:
Call create_list_from_shell with your command
The command's stdout is split by newlines to create list items
Empty lines are filtered out
Use the returned list_id with run_shell_across_list or run_agent_across_list
| Name | Required | Description | Default |
|---|---|---|---|
| command | Yes | Shell command to run. Its stdout will be split by newlines to create list items. Example: 'find src -name "*.ts"' or 'git ls-files' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description details behavior: runs command, splits stdout by newlines, filters empty lines, returns list_id. Lacks mention of error handling or permissions, but covers key aspects well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-organized with sections, examples, and a workflow. Every sentence adds value; no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description fully explains the tool's purpose, usage, behavior, and return value. Complete for a single-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage with description for the single parameter. Description adds context through examples and explanation of its role in creating list items, exceeding baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it creates a list by running a shell command and parsing newline-delimited output. It distinguishes from sibling 'create_list' by specifying the method (shell command vs manual specification).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'WHEN TO USE' section lists appropriate scenarios and directly contrasts with 'create_list' as an alternative. Provides examples and a workflow, giving clear guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deletes an existing list by its ID.
WHEN TO USE:
To clean up lists that are no longer needed
To free up memory after processing is complete
| Name | Required | Description | Default |
|---|---|---|---|
| list_id | Yes | The list ID returned by create_list. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It states deletion but does not mention permanence, cascading effects, or permission requirements. For a destructive operation, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and includes a structured 'WHEN TO USE' section. However, it could be more concise by removing the bullet points or integrating them into a sentence. Still efficient overall.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple one-parameter delete operation, the description is mostly adequate. However, it lacks details about irreversible effects or prerequisites, which would improve completeness for a destructive action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one parameter described as 'The list ID returned by create_list.' The description does not add further meaning beyond this, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Deletes' and the resource 'list by its ID', making the action clear. It distinguishes from sibling tools like create_list and get_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a 'WHEN TO USE' section with two clear scenarios (clean up lists, free memory). It does not explicitly state when not to use or mention alternatives, but provides enough context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves the items in an existing list by its ID.
WHEN TO USE:
To inspect the contents of a list before processing
To verify which items are in a list
To check if a list exists
| Name | Required | Description | Default |
|---|---|---|---|
| list_id | Yes | The list ID returned by create_list. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It implies a read-only operation ('retrieves') but does not explicitly state non-destructiveness, authentication needs, or behavior on missing list IDs. While adequate for a simple get, it lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: a single sentence followed by three bullet points. All information is front-loaded and every sentence serves a purpose with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with one parameter and no output schema, the description is largely complete. It covers purpose and usage context. However, it omits details about return format, error handling, and pagination, which would raise it to a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes the only parameter (list_id) as 'The list ID returned by create_list' with 100% coverage. The description adds no additional meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Retrieves the items in an existing list by its ID,' specifying the action (retrieves), resource (items in a list), and method (by ID). This distinguishes it from sibling tools like create_list or list_all_lists.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Includes a 'WHEN TO USE' section with three bullet points (inspect contents, verify items, check existence), providing clear context for when the tool is appropriate. However, it does not explicitly state when not to use or mention alternatives, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists all existing lists and their item counts.
WHEN TO USE:
To see all available lists in the current session
To find a list ID you may have forgotten
To check how many lists exist
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It correctly implies a read-only operation and lists output includes item counts, but lacks details on performance, data freshness, or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with a clear main sentence followed by a 'WHEN TO USE' list. Every sentence serves a purpose with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, no output schema), the description is reasonably complete: it states the action and output (list IDs and item counts) and provides usage guidance. Minor missing information about output format or limits.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has zero parameters, so schema coverage is 100%. The description does not need to add parameter meaning. Baseline score of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Lists all existing lists and their item counts', using a specific verb and resource. It distinguishes from sibling tools like get_list (single list) and create_list (creation).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a 'WHEN TO USE' section with three clear use cases. It does not explicitly mention when not to use or alternatives, but the guidance is sufficient for this simple tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Spawns an AI coding agent for each item in a previously created list. Agents run in batches of 10 parallel processes with automatic permission skipping enabled.
WHEN TO USE:
Performing complex code analysis, refactoring, or generation across multiple files
Tasks that require AI reasoning rather than simple shell commands
When you need to delegate work to multiple AI agents working in parallel
AVAILABLE AGENTS:
claude: Claude Code CLI (uses --dangerously-skip-permissions for autonomous operation)
gemini: Google Gemini CLI (uses --yolo for auto-accept)
codex: OpenAI Codex CLI (uses --dangerously-bypass-approvals-and-sandbox for autonomous operation)
opencode: OpenCode CLI (uses run command for non-interactive autonomous operation)
HOW IT WORKS:
Each item in the list is substituted into the prompt where {{item}} appears
Agents run in batches of 10 at a time to avoid overwhelming the system
Output streams directly to files as the agents work
This tool waits for all agents to complete before returning
AFTER COMPLETION:
Read the stdout files to check the results from each agent
Check stderr files if you encounter errors
Files are named based on the item (e.g., "myfile.ts.stdout.txt")
VARIABLE SUBSTITUTION:
Use {{item}} in your prompt - it will be replaced with each list item
Example: "Review {{item}} for bugs" becomes "Review src/file.ts for bugs" for item "src/file.ts"
| Name | Required | Description | Default |
|---|---|---|---|
| agent | Yes | Which AI agent to use: 'claude', 'gemini', 'codex', 'opencode'. All agents run with permission-skipping flags for autonomous operation. | |
| model | No | Optional model to use. Passed as --model to the agent CLI. Examples: 'claude-opus-4-6', 'claude-sonnet-4-6' for Claude; 'gemini-2.5-pro' for Gemini; 'o3' for Codex. | |
| prompt | Yes | The prompt to send to each agent. Use {{item}} as a placeholder - it will be replaced with the current item value. Example: 'Review {{item}} and suggest improvements' or 'Add error handling to {{item}}' | |
| list_id | Yes | The list ID returned by create_list. This identifies which list of items to iterate over. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does substantial work: batching of 10, automatic permission skipping, agent-specific flags, streaming output to files, and blocking until all agents finish. It falls just short of explicitly warning about potential filesystem modifications from autonomous agents.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average but well-organized with clear sections and front-loaded purpose. Some redundancy exists between HOW IT WORKS and VARIABLE SUBSTITUTION, but each section is otherwise purposeful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with no output schema or annotations, the description covers the input lifecycle, concurrency behavior, output file naming, and post-completion steps. It does not describe failure handling or partial-failure behavior, but the provided details are sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds meaningful context: how list_id connects to create_list, how {{item}} substitution works, and how agent choices map to CLI flags. This goes beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence states a precise verb, resource, and scope: it spawns an AI coding agent for each item in a previously created list. It also differentiates itself from the shell-based sibling by emphasizing AI reasoning and parallel agents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
A dedicated WHEN TO USE section gives concrete contexts: complex analysis, refactoring, generation, and tasks needing AI rather than simple shell commands. It does not include explicit when-not-to-use or name the sibling tool, but the contrast with shell commands provides clear routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Executes a shell command for each item in a previously created list. Commands run in batches of 10 parallel processes, with stdout and stderr streamed to separate files.
WHEN TO USE:
Running the same shell command across multiple files (e.g., linting, formatting, compiling)
Batch processing with command-line tools
Any operation where you need to execute shell commands on a collection of items
HOW IT WORKS:
Each item in the list is substituted into the command where $item appears
Commands run in batches of 10 at a time to avoid overwhelming the system
Output streams directly to files as the commands execute
This tool waits for all commands to complete before returning
AFTER COMPLETION:
Read the stdout files to check results
Check stderr files if you encounter errors or unexpected output
Files are named based on the item (e.g., "myfile.ts.stdout.txt")
VARIABLE SUBSTITUTION:
Use $item in your command - it will be replaced with each list item (properly shell-escaped)
Example: "cat $item" becomes "cat 'src/file.ts'" for item "src/file.ts"
| Name | Required | Description | Default |
|---|---|---|---|
| command | Yes | Shell command to execute for each item. Use $item as a placeholder - it will be replaced with the current item value (properly escaped). Example: 'wc -l $item' or 'cat $item | grep TODO' | |
| list_id | Yes | The list ID returned by create_list. This identifies which list of items to iterate over. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full burden. It discloses batching (10 parallel), output streaming to files, variable substitution, and that the tool waits for completion. Missing error handling details (e.g., partial failure) prevent a higher score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (WHEN TO USE, HOW IT WORKS, AFTER COMPLETION, VARIABLE SUBSTITUTION) and front-loaded with the core action. It is slightly lengthy but every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, usage, process, post-completion steps, and variable substitution. It lacks error handling behavior and edge cases (e.g., empty list). No output schema exists, but the return behavior (streaming to files) is explained. Overall, quite complete for a 2-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters described. The description adds value by explaining $item substitution, shell escaping, and providing examples, going beyond the schema's basic descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Executes a shell command for each item in a previously created list.' It distinguishes from sibling 'run_agent_across_list' by focusing on shell commands and provides specific batching and streaming details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'WHEN TO USE' section explicitly lists scenarios like linting, formatting, compiling, and batch processing. It does not explicitly mention alternatives or when not to use, but the context of siblings and the description's focus on shell commands provide adequate guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Updates an existing list by replacing its items with a new array.
WHEN TO USE:
To modify the contents of an existing list
To add or remove items from a list
To reorder items in a list
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | The new array of items to replace the existing list contents. | |
| list_id | Yes | The list ID returned by create_list. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral traits. It states the tool replaces items (destructive write), but fails to disclose other aspects like authorization needs, rate limits, or what happens to old data. This is adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences plus three bullet points, with no extraneous text. The core action is front-loaded, and every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 params, no output schema, no annotations), the description adequately covers the purpose and usage. It lacks details on return values or errors, but these are not critical for a straightforward update operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. The description's 'replaces its items with a new array' adds no new meaning beyond what the items parameter description already says. Thus, it meets the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Updates an existing list by replacing its items with a new array.' This provides a specific verb (update) and resource (list), and it distinguishes from siblings like create_list and get_list by focusing on modification.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a 'WHEN TO USE' section with three relevant bullet points (modify contents, add/remove items, reorder items). It does not explicitly exclude cases or mention alternatives, but the guidance is clear for typical use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.7run_agent_across_list1 field changedInput schema / properties / modelAdded value: +{
+ "description": "Optional model to use. Passed as --model to the agent CLI. Examples: 'claude-opus-4-6', 'claude-sonnet-4-6' for Claude; 'gemini-2.5-pro' for Gemini; 'o3' for Codex.",
+ "type": "string"
+}v1.0.0run_agent_across_list2 fields changedInput schema / properties / agent / descriptionPrevious value: -"Which AI agent to use: 'claude', 'gemini', 'codex'. All agents run with permission-skipping flags for autonomous operation."New value: +"Which AI agent to use: 'claude', 'gemini', 'codex', 'opencode'. All agents run with permission-skipping flags for autonomous operation."Input schema / properties / agent / enumPrevious value: -[
- "claude",
- "gemini",
- "codex"
-]New value: +[
+ "claude",
+ "gemini",
+ "codex",
+ "opencode"
+]create_listcreate_list_from_shelldelete_listget_listlist_all_listsrun_agent_across_listrun_shell_across_listupdate_listScored across 8 tools
Most tools are clearly distinct, but create_list and create_list_from_shell both create lists, which could cause minor confusion. However, the descriptions clearly differentiate manual entry vs. shell-command output, and all other tools (get/update/delete/list/runners) have unique purposes.
Tool names generally follow a verb_noun pattern (create_list, get_list, update_list, delete_list). Minor deviations include list_all_lists (repetitive) and run_shell_across_list/run_agent_across_list using a different prepositional style, but overall the convention is consistent.
Eight tools is well-scoped for a list-management and parallel-execution server: full CRUD for lists, two creation methods, and two execution modes. No redundancy or bloat.
The server covers the complete lifecycle: create lists from arrays or shell output, retrieve, update, delete, list all, and execute either shell commands or AI agents across list items. There are no obvious missing operations for the stated purpose.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
LLM chat, text tools, image generation, editing, batch image jobs, and asynchronous video generation
Shared control plane for AI coding agents — tasks, memory, decisions, file locks. 12 tools.
Cross-agent artifact workspace with provenance across Claude Code, Codex, Cursor, LangGraph.
