항목 목록에 대해 셸 명령과 AI 코딩 에이전트를 병렬로 실행하는 MCP(Model Context Protocol) 서버입니다. 파일을 일괄 처리하거나, 대상에 대해 린터를 실행하거나, 여러 에이전트에 작업을 위임하는 데 사용할 수 있습니다.
목록 관리: 파일 경로, URL, 식별자와 같은 항목 목록을 생성, 업데이트, 삭제, 조회합니다
병렬 셸 실행: 일괄 병렬 처리로 목록의 모든 항목에 대해 셸 명령을 실행합니다
멀티 에이전트 오케스트레이션: 항목을 처리하기 위해 Claude, Gemini 또는 Codex 에이전트를 병렬로 생성합니다
스트리밍 출력: 결과가 실시간으로 파일에 스트리밍되어 진행 상황을 모니터링할 수 있습니다
일괄 처리: 명령과 에이전트는 시스템에 과부하가 걸리지 않도록 10개씩 배치로 실행됩니다
Related MCP server: Claude Parallel Tasks MCP Server
npm install par5-mcp또는 전역으로 설치:
npm install -g par5-mcpMCP 클라이언트 구성에 추가:
{
"mcpServers": {
"par5": {
"command": "npx",
"args": ["par5-mcp"]
}
}
}또는 전역으로 설치한 경우:
{
"mcpServers": {
"par5": {
"command": "par5-mcp"
}
}
}create_list병렬 처리를 위한 명명된 항목 목록을 생성합니다.
매개변수:
items (string[]): 목록에 저장할 항목 배열
반환값: 다른 도구와 함께 사용할 고유 목록 ID
예시:
create_list(items: ["src/a.ts", "src/b.ts", "src/c.ts"])
// Returns: list_id = "abc-123-..."get_listID로 기존 목록의 항목을 검색합니다.
매개변수:
list_id (string): create_list가 반환한 목록 ID
update_list기존 목록의 항목을 새 배열로 교체하여 업데이트합니다.
매개변수:
list_id (string): 업데이트할 목록 ID
items (string[]): 새 항목 배열
delete_listID로 기존 목록을 삭제합니다.
매개변수:
list_id (string): 삭제할 목록 ID
list_all_lists모든 기존 목록과 항목 수를 나열합니다.
매개변수: 없음
run_shell_across_list목록의 각 항목에 대해 셸 명령을 실행합니다. 명령은 10개의 병렬 프로세스 배치로 실행됩니다.
매개변수:
list_id (string): 반복할 목록 ID
command (string): $item 자리 표시자가 포함된 셸 명령
변수 치환:
명령에 $item을 사용하세요. 각 목록 항목으로 대체되며 셸 이스케이프 처리됩니다.
예시:
run_shell_across_list(
list_id: "abc-123",
command: "wc -l $item"
)이렇게 하면 wc -l 'src/a.ts', wc -l 'src/b.ts' 등이 병렬로 실행됩니다.
출력:
표준 출력과 표준 오류는 항목별로 별도의 파일에 스트리밍됩니다
결과를 읽을 수 있도록 파일 경로가 반환됩니다
run_agent_across_list목록의 각 항목에 대해 AI 코딩 에이전트를 생성합니다. 에이전트는 에이전트당 5분 제한 시간으로 10개씩 배치로 실행됩니다.
매개변수:
list_id (string): 반복할 목록 ID
agent (enum): "claude", "gemini" 또는 "codex"
prompt (string): {{item}} 자리 표시자가 포함된 프롬프트
사용 가능한 에이전트:
에이전트 | CLI | 자동 승인 플래그 |
| Claude Code CLI |
|
| Google Gemini CLI |
|
| OpenAI Codex CLI |
|
변수 치환:
프롬프트에 {{item}}을 사용하세요. 각 목록 항목으로 대체됩니다
예시:
run_agent_across_list(
list_id: "abc-123",
agent: "claude",
prompt: "Review {{item}} for security vulnerabilities and suggest fixes"
)출력:
표준 출력과 표준 오류는 항목별로 별도의 파일에 스트리밍됩니다
에이전트 출력을 읽을 수 있도록 파일 경로가 반환됩니다
여러 파일을 처리하는 일반적인 워크플로는 다음과 같습니다:
처리할 파일 목록을 생성합니다:
create_list(items: ["src/auth.ts", "src/api.ts", "src/utils.ts"])모든 파일에 대해 셸 명령을 실행합니다:
run_shell_across_list(
list_id: "<returned-id>",
command: "cat $item | grep -n 'TODO'"
)또는 AI 에이전트에 위임합니다:
run_agent_across_list(
list_id: "<returned-id>",
agent: "claude",
prompt: "Add comprehensive JSDoc comments to all exported functions in {{item}}"
)출력 파일을 읽어 결과를 확인합니다
정리:
delete_list(list_id: "<returned-id>")다음 환경 변수를 사용하여 par5-mcp를 구성할 수 있습니다:
변수 | 설명 | 기본값 |
| 배치당 병렬 프로세스 수 |
|
| 모든 에이전트에 전달되는 추가 인수 | (없음) |
| Claude CLI에 전달되는 추가 인수 | (없음) |
| Gemini CLI에 전달되는 추가 인수 | (없음) |
| Codex CLI에 전달되는 추가 인수 | (없음) |
| 아무 값으로 설정하면 Claude 에이전트를 비활성화합니다 | (없음) |
| 아무 값으로 설정하면 Gemini 에이전트를 비활성화합니다 | (없음) |
| 아무 값으로 설정하면 Codex 에이전트를 비활성화합니다 | (없음) |
예시:
{
"mcpServers": {
"par5": {
"command": "npx",
"args": ["par5-mcp"],
"env": {
"PAR5_BATCH_SIZE": "20",
"PAR5_CLAUDE_ARGS": "--model claude-sonnet-4-20250514"
}
}
}
}결과는 시스템 임시 디렉터리의 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
└── ...파일 이름은 항목 값에서 파생됩니다(파일 시스템 안전을 위해 정리됨).
변경 사항을 제안하기 전에 Discussion을 시작해 주세요. 제안이 수락되면 Mathematic 유지관리자 또는 AI 에이전트가 이를 구현하고 풀 리퀘스트를 엽니다. 해당 풀 리퀘스트를 Discussion에 연결하고 제안의 원작자로 표시합니다. GitHub는 풀 리퀘스트 생성을 Mathematic 유지관리자, 쓰기/유지관리/관리자 액세스 권한이 있는 저장소 협업자, 그리고 승인된 유지관리 에이전트로 제한합니다. 전체 프로세스는 CONTRIBUTING.md를 참조하세요.
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+
run_agent_across_list의 경우:
claude 에이전트는 Claude Code CLI 설치가 필요합니다
gemini 에이전트는 Gemini CLI 설치가 필요합니다
codex 에이전트는 Codex CLI 설치가 필요합니다
Apache-2.0
이 프로젝트는 501(c)(3) 비영리 단체의 무료 오픈소스 작업물입니다. 유용하게 사용하셨다면 기부를 고려해 주세요.
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).
