Un servidor MCP (Model Context Protocol) que ejecuta comandos de shell y agentes de codificación de IA en paralelo sobre listas de elementos. Úsalo para procesar archivos por lotes, ejecutar linters sobre objetivos o delegar trabajo a múltiples agentes.
Gestión de listas: Crea, actualiza, elimina e inspecciona listas de elementos como rutas de archivo, URL e identificadores.
Ejecución de shell en paralelo: Ejecuta comandos de shell en todos los elementos de una lista con paralelismo por lotes.
Orquestación multiagente: Lanza agentes de Claude, Gemini o Codex en paralelo para procesar elementos.
Salida en streaming: Los resultados se transmiten a archivos en tiempo real para supervisar el progreso.
Procesamiento por lotes: Los comandos y agentes se ejecutan en lotes de 10 para no saturar el sistema.
Related MCP server: Claude Parallel Tasks MCP Server
npm install par5-mcpO instala globalmente:
npm install -g par5-mcpAñade a la configuración de tu cliente MCP:
{
"mcpServers": {
"par5": {
"command": "npx",
"args": ["par5-mcp"]
}
}
}O si está instalado globalmente:
{
"mcpServers": {
"par5": {
"command": "par5-mcp"
}
}
}create_listCrea una lista con nombre de elementos para el procesamiento en paralelo.
Parámetros:
items (string[]): Matriz de elementos para almacenar en la lista.
Devuelve: Un ID de lista único para usar con otras herramientas.
Ejemplo:
create_list(items: ["src/a.ts", "src/b.ts", "src/c.ts"])
// Returns: list_id = "abc-123-..."get_listRecupera los elementos de una lista existente por su ID.
Parámetros:
list_id (string): El ID de lista devuelto por create_list.
update_listActualiza una lista existente reemplazando sus elementos con una nueva matriz.
Parámetros:
list_id (string): El ID de lista a actualizar.
items (string[]): La nueva matriz de elementos.
delete_listElimina una lista existente por su ID.
Parámetros:
list_id (string): El ID de lista a eliminar.
list_all_listsEnumera todas las listas existentes y sus recuentos de elementos.
Parámetros: Ninguno.
run_shell_across_listEjecuta un comando de shell para cada elemento de una lista. Los comandos se ejecutan en lotes de 10 procesos en paralelo.
Parámetros:
list_id (string): El ID de lista sobre el que iterar.
command (string): Comando de shell con el marcador de posición $item.
Sustitución de variables:
Usa $item en tu comando. Se reemplazará por cada elemento de la lista y se escapará para shell.
Ejemplo:
run_shell_across_list(
list_id: "abc-123",
command: "wc -l $item"
)Esto ejecuta wc -l 'src/a.ts', wc -l 'src/b.ts', etc. en paralelo.
Salida:
La salida estándar y el error estándar se transmiten a archivos separados por elemento.
Se devuelven las rutas de los archivos para que leas los resultados.
run_agent_across_listLanza un agente de codificación de IA para cada elemento de una lista. Los agentes se ejecutan en lotes de 10 con un tiempo de espera de 5 minutos por agente.
Parámetros:
list_id (string): El ID de lista sobre el que iterar.
agent (enum): "claude", "gemini" o "codex".
prompt (string): Prompt con el marcador de posición {{item}}.
Agentes disponibles:
Agente | CLI | Indicador de aceptación automática |
| Claude Code CLI |
|
| Google Gemini CLI |
|
| OpenAI Codex CLI |
|
Sustitución de variables:
Usa {{item}} en tu prompt - se reemplazará por cada elemento de la lista.
Ejemplo:
run_agent_across_list(
list_id: "abc-123",
agent: "claude",
prompt: "Review {{item}} for security vulnerabilities and suggest fixes"
)Salida:
La salida estándar y el error estándar se transmiten a archivos separados por elemento.
Se devuelven las rutas de los archivos para que leas las salidas de los agentes.
Este es un flujo de trabajo típico para procesar múltiples archivos:
Crea una lista de archivos para procesar:
create_list(items: ["src/auth.ts", "src/api.ts", "src/utils.ts"])Ejecuta un comando de shell en todos los archivos:
run_shell_across_list(
list_id: "<returned-id>",
command: "cat $item | grep -n 'TODO'"
)O delega en agentes de IA:
run_agent_across_list(
list_id: "<returned-id>",
agent: "claude",
prompt: "Add comprehensive JSDoc comments to all exported functions in {{item}}"
)Lee los archivos de salida para comprobar los resultados
Limpia:
delete_list(list_id: "<returned-id>")Las siguientes variables de entorno se pueden usar para configurar par5-mcp:
Variable | Descripción | Por defecto |
| Número de procesos paralelos por lote |
|
| Argumentos adicionales pasados a todos los agentes | (ninguno) |
| Argumentos adicionales pasados a la CLI de Claude | (ninguno) |
| Argumentos adicionales pasados a la CLI de Gemini | (ninguno) |
| Argumentos adicionales pasados a la CLI de Codex | (ninguno) |
| Establecer cualquier valor para desactivar el agente de Claude | (ninguno) |
| Establecer cualquier valor para desactivar el agente de Gemini | (ninguno) |
| Establecer cualquier valor para desactivar el agente de Codex | (ninguno) |
Ejemplo:
{
"mcpServers": {
"par5": {
"command": "npx",
"args": ["par5-mcp"],
"env": {
"PAR5_BATCH_SIZE": "20",
"PAR5_CLAUDE_ARGS": "--model claude-sonnet-4-20250514"
}
}
}
}Los resultados se escriben en archivos temporales en el directorio temporal del sistema bajo 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
└── ...Los nombres de archivo se derivan del valor del elemento (saneado para la seguridad del sistema de archivos).
Por favor, [inicia una Discusión] antes de proponer un cambio. Si aceptamos la propuesta, un mantenedor de Mathematic o un agente de IA la implementará y abrirá una solicitud de extracción. Vincularemos esa solicitud de extracción a la Discusión y acreditaremos al autor original de la propuesta. GitHub restringe la creación de solicitudes de extracción a los mantenedores de Mathematic, a los colaboradores del repositorio con acceso de escritura, mantenimiento o administración, y a los agentes de mantenimiento autorizados. Consulta CONTRIBUTING.md para conocer el proceso completo.
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+
Para run_agent_across_list:
el agente claude requiere Claude Code CLI instalado
el agente gemini requiere Gemini CLI instalado
el agente codex requiere Codex CLI instalado
Apache-2.0
Este proyecto es un trabajo gratuito y de código abierto realizado por una organización sin fines de lucro 501(c)(3). Si te resulta útil, considera la posibilidad de donar.
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
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
Backend for AI agents: one batched tool over ~668 actions (hosting, storage, auth, payments).
