Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@claude-subagents-mcp Spawn four subagents to review the code, tests, docs, and security of this repo."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Python stdlib MCP server that delegates tasks to up to four parallel Claude subagents, with optional workspace file access and per-agent model and reasoning effort configuration. Other stdio MCP clients are also supported.
Parallel agent orchestration -- spawn up to four concurrent Claude subagents, each with its own task, model, and reasoning effort
Async spawn/wait pattern -- agents run in background worker processes; your main session continues working while they do
Cursor-based result delivery -- wait on multiple agents at once, receive each result exactly once, and track delivery with cursors
Workspace file access -- optionally grant agents scoped read or read/write access to a directory, with path restrictions that exclude .git, .codex, and .agents
Follow-up messages -- send corrections or additional instructions to running or idle agents without restarting their context
Model and effort selection -- choose any model advertised by your proxy, with configurable reasoning effort that adapts automatically for models that lack effort support
Durable task state -- agent progress persists to disk across MCP client restarts; recover tasks by ID or optional request key
Deduplication -- identical in-flight tasks are detected and reused, preventing accidental double-spawns after transport failures
No external dependencies -- runs on Python 3.11+ using only the standard library
Batch file reads -- agents can read up to 16 files in a single tool call, reducing round trips during source review
Related MCP server: claude-orchestrator
Python 3.11 or later
An Anthropic-compatible API endpoint (local proxy or https://api.anthropic.com)
Clone the repository and install:
git clone https://github.com/jordankzf/claude-subagents-mcp.git
cd claude-subagents-mcp
python -m pip install .You can also install directly from GitHub:
pip install git+https://github.com/jordankzf/claude-subagents-mcp.gitThis project is not published to PyPI.
After installation, the server is available as a console command:
claude-subagents-mcpOr run it directly:
python claude_subagents_mcp.pyThe server communicates over stdio using the MCP JSON-RPC protocol. Configure your MCP client to launch the command and connect over stdin/stdout.
Create or edit your Codex MCP configuration to include the server. See examples/codex-config.toml for a working template:
[mcp_servers.claude-subagents]
command = "claude-subagents-mcp"
tool_timeout_sec = 65
env_vars = ["ANTHROPIC_API_KEY"]
[mcp_servers.claude-subagents.env]
ANTHROPIC_BASE_URL = "https://api.anthropic.com"
CLAUDE_DEFAULT_MODEL = "claude-fable-5-1"
CLAUDE_DEFAULT_REASONING_EFFORT = "medium"The env_vars array forwards ANTHROPIC_API_KEY from your shell environment into the Codex process, which passes it through to the MCP server. The env table sets additional configuration directly. Never commit secrets to the repository or to this file; set ANTHROPIC_API_KEY in your environment instead.
You can also configure all settings through environment variables in your shell before launching Codex:
export ANTHROPIC_API_KEY="your-api-key"
export ANTHROPIC_BASE_URL="https://api.anthropic.com"
export CLAUDE_DEFAULT_MODEL="claude-fable-5-1"
export CLAUDE_DEFAULT_REASONING_EFFORT="medium"Variable | Default | Description |
| (none, recommended) | API key for the configured Anthropic-compatible endpoint |
| (none) | Legacy alias for |
|
| Base URL of the API endpoint. Configurable to any Anthropic-compatible service including |
|
| Default model ID passed to the endpoint |
|
| Default reasoning effort: |
| (platform default) | Directory for persisted task state. On Windows: |
Tool | Description |
| Spawn an independent subagent with a task, optional workspace, model, and effort. Returns an agent ID immediately |
| Read agent status, activity, changed files, and result. Optionally wait up to 10 seconds |
| Wait for the first of up to four agents to finish (max 50 seconds). Returns full result with cursors for once-only delivery |
| Send a follow-up to a running or idle agent. Running agents receive it at the next response boundary; idle agents resume |
| Cancel an active task. Prevents further file operations; already-pending API requests may complete in the background |
| Recovery only: compact summaries of recent agents. Normally use the ID from spawn directly with |
| List models advertised by the proxy and current bridge defaults. Use when choosing a model, not before every spawn |
| Start a consultation and return an agent ID immediately. Collect the answer with |
Each agent can target a specific model and reasoning effort level. The defaults are claude-fable-5-1 and medium, configurable through environment variables.
Available effort levels: default, low, medium, high, xhigh, max.
Setting effort to default omits the effort parameter from the API request entirely, letting the provider decide.
Automatic adaptation with reported adjustment: When a model is known not to support effort control (or when the proxy explicitly rejects it), inherited effort settings are automatically omitted. The server remembers which models lack effort support and omits the parameter on future requests. The adjustment is not silent: the configuration_note field in the response explains what was changed and why.
Explicit choices are honored or rejected clearly. If you explicitly set reasoning_effort on a spawn call and the model does not support it, the request fails with a clear error rather than changing your intent. This distinction between inherited defaults and explicit choices prevents surprising behavior.
Unknown model capabilities are not guaranteed. A model not yet tested for effort support will attempt the request as configured; if the provider rejects it and the effort was inherited, it retries once without effort and reports the adjustment. If the effort was explicit, the failure is reported.
Up to four concurrent agents. Additional spawns are rejected until an active agent completes or is cancelled.
Spawn and wait timeouts. wait_claude_agents accepts up to 50 seconds. Individual tasks default to 300 seconds (configurable 10 to 900).
Cursor-based delivery. Each terminal result is delivered exactly once per wait call. Pass the returned cursors object back on subsequent waits to avoid re-receiving completed results.
No shell, browser, or native panel access. Subagents can only use the file tools provided by the server (list, read, batch read, write). They cannot execute commands, open browsers, or display UI.
Workspace path restrictions are not an OS sandbox. File access is scoped to the provided workspace directory through path validation, but this is application-level enforcement, not kernel-level isolation.
Prompts and file contents are sent to the configured endpoint. Be mindful of what you include in tasks and workspaces.
Task histories are stored locally and may contain sensitive material. The state directory should be treated accordingly.
CI covers Windows, Linux, and macOS with Python 3.11 through 3.13. Windows has additional live testing.
This is an initial 0.1.0 release, not a production guarantee. Expect rough edges.
spawn_claude_agent(task="Analyze the error handling in src/api.py", workspace="/path/to/project")
-> { agent_id: "abc123...", status: "queued" }
wait_claude_agents(agent_ids=["abc123..."])
-> { results: [{ agent_id: "abc123...", status: "completed", result: "..." }], cursors: {...} }spawn_claude_agent(task="Review authentication module", workspace="/project", task_name="auth-review")
spawn_claude_agent(task="Review database layer", workspace="/project", task_name="db-review")
wait_claude_agents(agent_ids=["id1", "id2"], timeout_seconds=45)
-> { results: [first completed], pending: [still running], cursors: {"id1": 3} }
wait_claude_agents(agent_ids=["id1", "id2"], timeout_seconds=45, cursors={"id1": 3})
-> { results: [second completed], cursors: {"id1": 3, "id2": 5} }ask_claude(prompt="Summarize the key differences between these two approaches")
-> { agent_id: "def456...", status: "queued" }
wait_claude_agents(agent_ids=["def456..."])
-> { results: [{ agent_id: "def456...", status: "completed", result: "..." }], cursors: {...} }send_claude_message(agent_id="abc123...", message="Also check for SQL injection risks")
wait_claude_agents(agent_ids=["abc123..."])The test suite uses unittest and does not make live API calls:
python -m unittest discover -s testsCI runs this suite on Windows, Linux, and macOS across Python 3.11, 3.12, and 3.13.
See CONTRIBUTING.md for guidelines on reporting issues, suggesting features, and submitting pull requests.
See SECURITY.md for the security model, known boundaries, and responsible disclosure guidance.
MIT -- Copyright 2026 jordankzf
Start a Claude consultation and return an agent ID immediately. A queued/running result is NOT a timeout. Collect the answer using get_claude_agent; never resubmit just because it is pending. For workspace work use spawn_claude_agent.
| Name | Required | Description | Default |
|---|---|---|---|
| model | No | Optional proxy model ID. Omit for configured default (claude-fable-5-1 unless changed). Use list_claude_models if needed. | |
| prompt | Yes | ||
| messages | No | ||
| max_tokens | No | Output ceiling, including thinking. Omit for automatic budget: 65536 at xhigh/max, otherwise 8192. Model limits apply. | |
| reasoning_effort | No | Optional reasoning effort. Omit to inherit the configured default, adapted automatically for models without effort support. Explicit choices are honored or rejected clearly. default omits the provider effort parameter. Effective settings and any adjustment are returned. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and discloses key behavior: the call returns immediately with an agent ID, results are queued/running, and a pending status is not a timeout. It could add outcome or failure details, but the essential async behavior is clearly exposed.
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?
Three sentences, all high-signal: the first states the core mechanism, the second prevents a common misuse, the third routes to the correct sibling. No filler or redundant restatement of the tool name.
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 an asynchronous creation tool with no output schema, the description covers the required follow-up (get_claude_agent), the non-timeout nature of pending results, and the sibling to use for workspace work. It lacks explicit mention of cancellation or waiting tools, but the essential invocation context is complete.
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 description coverage is moderate (60%); model, max_tokens, and reasoning_effort are already documented in the schema, while prompt and messages are left to their names and structure. The description adds no extra parameter semantics, so it stays at the baseline rather than improving on the schema.
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 a specific verb ('Start') with a clear resource ('a Claude consultation') and states the immediate output ('return an agent ID'). It distinguishes itself from spawn_claude_agent by excluding workspace work, and from get_claude_agent by framing it as the collection step.
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?
It gives direct workflow guidance: collect the answer via get_claude_agent, never resubmit while pending, and use spawn_claude_agent for workspace work. This tells an agent exactly when this tool is appropriate and which sibling to choose instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cancel a delegated task. Prevents subsequent file operations; an already pending proxy request may finish in the background. Existing edits are retained.
| Name | Required | Description | Default |
|---|---|---|---|
| agent_id | Yes | Agent ID returned by spawn or ask_claude. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It meaningfully explains that only subsequent file operations are prevented, that an already pending proxy request may finish in the background, and that existing edits are retained. This gives an agent a realistic model of cancellation semantics rather than just 'cancel this thing'.
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 tight sentences with no filler. It front-loads the core purpose, then adds only the behavioral details that materially affect an agent's expectations. Every clause earns its place.
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 one-parameter mutating action with no output schema and no annotations, the description adequately explains what the tool does, what it prevents, and what it preserves. Minor gaps are the lack of error/status behavior and what happens to callers waiting on the canceled agent, but these are not essential for basic 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 description coverage is 100%, with agent_id already documented as 'Agent ID returned by spawn or ask_claude'. The tool description adds no parameter-level meaning, but the schema already provides sufficient guidance, so the baseline of 3 applies.
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 opens with 'Cancel a delegated task', a specific verb plus resource that clearly identifies the operation. It is easily distinguished from siblings like spawn_claude_agent, list_claude_agents, and wait_claude_agents. The extra behavioral notes reinforce the purpose without obscuring it.
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 states what the tool does but does not explicitly say when to use it over alternatives or when not to use it. An agent must infer from the verb 'cancel' that this is for terminating delegated tasks rather than creating, listing, or waiting on them. No exclusions or alternative routing are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read Claude agent status, recent activity, changed files, and final result. Optionally wait up to 10 seconds. Tasks persist across Codex restarts.
| Name | Required | Description | Default |
|---|---|---|---|
| agent_id | Yes | Agent ID returned by spawn or ask_claude. | |
| wait_seconds | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for safety. It states the operation is read-only, discloses the optional wait behavior, and adds a meaningful behavioral fact: tasks persist across Codex restarts. It does not cover idempotency or whether reading consumes or moves the task state, but it provides several concrete observations beyond the strict minimum.
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 three tight sentences, front-loaded with the core purpose, then augmenting with the optional wait and persistence detail. There is no filler or repetition; every sentence contributes new, actionable information.
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 two-parameter tool with no output schema, the description captures the required agent_id concept, the optional wait limit, the read-only nature, and the persistence behavior. It mentions the pieces of data returned without defining their structure, but the absence of an output schema makes this acceptable. It lacks failure/error handling notes, but the essential context is present.
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 only ~50% (agent_id has a description, wait_seconds does not). The description compensates for the missing wait_seconds semantics by explaining that the tool can 'wait up to 10 seconds,' which also aligns with the schema's minimum 0 and maximum 10. The agent_id parameter is already well described in the schema, so this level of compensation is adequate.
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 'Read' and identifies the resource as 'Claude agent status, recent activity, changed files, and final result.' This clearly distinguishes it from sibling tools such as 'spawn_claude_agent' (creating), 'cancel_claude_agent' (cancelling), and 'wait_claude_agents' (waiting), without needing to consult their schemas.
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 gives a clear context — it reads an agent's status and can optionally wait — but it never references sibling tools like 'wait_claude_agents' or states when to use this tool over the others. There are no along explicit when-not or alternative conditions; usage guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recovery only: compact recent agent summaries, without full reports. Normally use the ID returned by spawn directly with wait_claude_agents.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral burden. It discloses that output is compact summaries, not full reports, and that this is not the normal path. However, it does not describe what a summary contains (e.g., whether IDs are included), ordering, limits, or the read-only nature explicitly.
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?
Two short sentences with no filler. The recovery-only purpose is front-loaded, and the routing guidance to wait_claude_agents earns its place.
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 tool is simple and the usage context is clear, but there is no output schema, so the description should explain what the returned 'summaries' actually contain—especially whether agent IDs are present for recovery. Without that, an agent may not know how to use the result with wait_claude_agents.
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 tool has zero parameters and the schema is empty with 100% coverage, so the baseline score of 4 applies. There is no parameter documentation burden on the description.
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 identifies the resource ('claude agents') and the key distinction: it returns 'compact recent agent summaries, without full reports.' It does not explicitly use the verb 'list,' but the name plus the noun phrase make the operation clear, and it distinguishes itself from the normal wait/spawn flow.
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?
Explicitly states this is 'recovery only' and gives the normal alternative: use the ID returned by spawn directly with wait_claude_agents. This tells the agent exactly when to choose this tool versus the preferred path.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List model IDs advertised by the local proxy and current bridge defaults. Use when choosing a different model, not before every spawn. Effort support varies by model.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral disclosure burden. It adds a useful behavioral note about 'Effort support varies by model' and 'List' implies a safe read operation. However, it does not disclose return format, potential absence of models, or any other runtime behavior an agent might need to anticipate.
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?
Two sentences with no filler. The core purpose is front-loaded in the first sentence, and the usage nuance is delivered in the second. Every word earns its place.
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 (zero parameters, no output schema), the description covers the essential context: what it lists, when to use it, and a key behavioral caveat about effort support. It is complete enough for an agent to decide when to invoke it, though a bit more detail on the output shape would be nice.
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 tool has zero parameters, so the baseline is 4. The description adds context about what the returned data represents (model IDs and bridge defaults), which is sufficient since there are no parameters to document.
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 states a specific verb ('List') and resource ('model IDs advertised by the local proxy and current bridge defaults'). This clearly distinguishes it from sibling agent-focused tools like list_claude_agents, and there is no ambiguity about what is being listed.
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 explicit usage guidance: 'Use when choosing a different model, not before every spawn.' This tells the agent when to call it and when not to. It does not explicitly name an alternative tool, but the sibling list makes the alternative tools apparent, so the guidance is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a follow-up to a Claude subagent. Running agents receive it at the next model-response boundary; idle agents resume with existing context. Returns promptly. Wait on the same agent ID for results.
| Name | Required | Description | Default |
|---|---|---|---|
| message | Yes | ||
| agent_id | Yes | Agent ID returned by spawn or ask_claude. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the full behavioral burden and does meaningful work: it discloses message delivery timing, idle-agent resumption, prompt return, and where to collect results. It omits error conditions or auth requirements, but the core execution model is transparent.
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?
Three sentences, each carrying distinct value: purpose, delivery behavior, and result-collection guidance. No fluff, front-loaded action, and the delivery mechanism is stated efficiently.
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 two-parameter tool with no annotations and no output schema, the description covers the important action and return-handling path ('Returns promptly. Wait on the same agent ID for results'). It omits validation or failure behavior, but the practical invocation loop is complete.
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 documents agent_id with a meaningful description, while message only has a type. The description adds that this is a 'follow-up,' giving some context about message intent, but it does not specify format, length, or content expectations. At 50% schema coverage, more parameter detail would help, but the minimal extra is acceptable.
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 states a specific verb and resource: 'Send a follow-up to a Claude subagent.' This is clearly distinct from siblings such as spawn_claude_agent, cancel_claude_agent, and wait_claude_agents, and leaves little ambiguity about what the tool does.
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?
It provides clear operational context: running agents receive the message at the next boundary, idle agents resume with context, and the caller should 'Wait on the same agent ID for results.' It stops short of explicitly naming alternatives like ask_claude or saying when not to use it, but the intended use case is well conveyed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Spawn an independent Claude subagent. Save the returned ID, continue your own work, then call wait_claude_agents directly. No listing step is needed. No shell or browsing tools.
| Name | Required | Description | Default |
|---|---|---|---|
| task | Yes | ||
| model | No | Optional proxy model ID. Omit for configured default (claude-fable-5-1 unless changed). Use list_claude_models if needed. | |
| max_steps | No | ||
| task_name | No | Short human-readable task label. | |
| workspace | No | Absolute directory the agent may access. Omit for reasoning-only tasks. | |
| max_tokens | No | Output ceiling, including thinking. Omit for automatic budget: 65536 at xhigh/max, otherwise 8192. Model limits apply. | |
| request_id | No | Optional unique request key; reuse after a transport failure to recover the same task, even if completed. | |
| allow_writes | No | Enable file creation/edits inside the workspace only when within the user-authorized task. | |
| timeout_seconds | No | ||
| reasoning_effort | No | Optional reasoning effort. Omit to inherit the configured default, adapted automatically for models without effort support. Explicit choices are honored or rejected clearly. default omits the provider effort parameter. Effective settings and any adjustment are returned. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses that the agent is independent, that the call is non-blocking ('continue your own work'), that the lifecycle continues via wait_claude_agents, and that the agent has no shell or browsing tools. It does not mention potential file-write side effects, though allow_writes is documented in the schema.
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?
Four short sentences, each earning its place: purpose, workflow, a negative instruction about listing, and capability boundaries. The core purpose is front-loaded and there is no filler.
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 10 parameters and a rich schema, the description adequately covers the high-level lifecycle and behavioral constraints. The main gaps are the lack of an explicit output-shape statement beyond 'returned ID' and no direct comparison to ask_claude, but the task is still callable correctly with the provided schema and workflow.
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 only 70%, but the description contributes no parameter-level meaning at all. The undocumented parameters—task, max_steps, and timeout_seconds—receive no clarification in the description, and the existing schema descriptions must carry the entire burden.
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 opens with 'Spawn an independent Claude subagent,' stating a specific verb (spawn), resource (Claude subagent), and a key differentiator (independent). This clearly separates it from the sibling tools that wait, list, get, or cancel 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?
It gives concrete workflow guidance: 'Save the returned ID, continue your own work, then call wait_claude_agents directly' and 'No listing step is needed.' It does not explicitly contrast with the synchronous ask_claude sibling, so it stops short of a full when-vs-alternatives explanation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Wait for the first of up to four specified Claude agents to finish or fail; returns its full result directly. No list/get cycle. Save returned cursors to avoid receiving the same result twice. Timeout means work remains pending.
| Name | Required | Description | Default |
|---|---|---|---|
| cursors | No | Per-agent cursors returned by a previous wait. | |
| agent_ids | Yes | ||
| timeout_seconds | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses that only the first finished/failed agent's result is returned, that cursors prevent duplicate results, and that a timeout means work remains pending. It does not cover all edge cases, but these are meaningful behavioral traits beyond the schema.
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?
Four short, information-dense sentences with no filler. Each sentence adds a distinct useful fact: purpose, result delivery, cursor guidance, and timeout semantics.
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 tool with no annotations and no output schema, the description is strong: it explains what happens, what the caller should do with cursors, and what a timeout implies. It could mention explicit error/failure behavior in more detail, but the core usage is complete.
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 low, and the description compensates by explaining the up-to-four limit, cursor reuse semantics, and timeout meaning. It adds clarity beyond the raw parameter names, though timeout_seconds lacks explicit numeric behavior beyond 'work remains pending.'
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 begins with a specific action ('Wait for the first... to finish or fail') tied to a clear resource (Claude agents) and a concrete result ('returns its full result directly'). It differentiates itself from list/get polling by explicitly saying 'No list/get cycle.'
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 gives actionable usage guidance: save returned cursors to avoid duplicate results. The phrase 'No list/get cycle' implies this tool replaces polling. It lacks explicit 'when not to use' or named alternatives, but the intended context is clear.
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.1.0ask_claudecancel_claude_agentget_claude_agentlist_claude_agentslist_claude_modelssend_claude_messagespawn_claude_agentwait_claude_agentsScored across 8 tools
Most tools have clearly distinct roles: spawn, wait, get, cancel, send, and list models are well separated. The main possible confusion is between ask_claude and spawn_claude_agent, but the descriptions explicitly distinguish consultation from workspace subagent work.
The dominant verb_noun pattern is consistent (spawn_claude_agent, cancel_claude_agent, get_claude_agent, list_claude_models). Minor deviations include ask_claude lacking a noun and singular/plural inconsistency between agent and agents.
Eight tools is well-scoped for managing the Claude subagent lifecycle: spawn, wait, get, cancel, message, list models, ask, and a recovery list. Each tool has a clear purpose without feeling bloated or thin.
The core lifecycle is well covered: spawning, waiting, polling, canceling, and follow-up messaging are all present. Minor gaps remain, such as no direct tool for listing all active agents or waiting on more than four at once, but these are workable limitations.
Cross-agent artifact workspace with provenance across Claude Code, Codex, Cursor, LangGraph.
Agent-native collaboration network: orchestrate a team of long-running agents from any MCP client.
Build and supervise fleets of agents from Claude Code, Codex or Cursor. Connects over OAuth.
The back-office workspace for your team's AIs: tasks, knowledge and context shared over MCP.
