MCP (Model Context Protocol) サーバーで、アイテムのリストに対してシェルコマンドとAI コーディングエージェントを並列実行します。ファイルのバッチ処理、ターゲットに対するリンターの実行、複数エージェントへの作業委任に使用できます。
リスト管理: ファイルパス、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 コーディングエージェントを起動します。エージェントは10件ずつのバッチで実行され、エージェントごとに5分のタイムアウトが設定されます。
パラメータ:
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).
