A
licenseA
qualityB
maintenanceWraps the Claude Agent SDK as MCP servers, letting you spawn multiple specialized Claude Code agents — each with its own model, tools, system prompt, and personality — from any MCP client.
5
358
19
ISC
Agent Fleet MCP Server
by Magic-Man-us
Click on "Install 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., "@Agent Fleet MCP Servercreate an agent for summarizing meeting notes"
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.
agent-fleet
Assembles a minimal Claude Agent SDK agent from a problem statement and a capability corpus, then runs and resumes it. The generation path is deterministic — no LLM and no network in it, so the same request and corpus produce a byte-identical agent. Running the agent is the part that talks to the SDK.
The runtime remains Claude Agent SDK-specific: Claude is the supervisor and conversation owner.
Live and generated Claude agents also receive one guarded in-process MCP tool,
mcp__codex__codex_run, for delegating bounded implementation, debugging, and independent-review
work to the local Codex CLI. Codex is a worker capability, not a second fleet runtime or an
authoritative workflow store.
Repository layout
Python only. One PyPI package (claude-sdk-agent-fleet), three subpackages layered so each depends on the ones
below it. pip install claude-sdk-agent-fleet gets the core engine and MCP pool server;
claude-sdk-agent-fleet[api] (or [all]) adds the FastAPI service.
Path | What it is | Run or import | Install |
| core engine: pipeline, router, pool | imported |
|
| FastAPI service over the core | run |
|
| MCP server exposing the pool as tools ( | run |
|
agent_fleet_api ─┐
├─imports──▶ agent_fleet ──imports──▶ capdisc
agent_fleet_mcp ─┘The API front-end carries the web dependencies as an optional extra so the core engine carries none by default. Environment scanning lives in capdisc, a separate, public repo consumed as a pinned git dependency.
Related MCP server: agentforge
Pipeline
ProblemRequest ─▶ recall ─▶ select ─▶ compose ─▶ score ─▶ render
(source) (budget) (AgentSpec) (efficiency) (SDK program)recall — a
CatalogSourceranks the corpus by lexical relevance (a pluggableRanker) and trims to a limit.select — keep candidates above a relevance threshold (plus pinned), capped by tool/skill budgets.
compose — map the selected refs into an
AgentSpecwith a templated system prompt.score — check the spec against tool/skill/prompt budgets (
efficiency).render — emit a runnable Claude Agent SDK program.
Pool
AgentPool (SQLite) keys each pooled agent by a stable AgentKey and stores the AgentSpec and
session id that built it, so a run can be retrieved, resumed against the same live SDK
conversation, or found fuzzily. run_with_capture observes the live message stream to record the
real, resumable session id of every agent a run involves — the top-level agent and each dispatched
subagent. Runs, per-agent runs, and findings are persisted alongside the entry.
Teammates
The pool's primary MCP surface: a hardcoded roster of templated teammates
(src/agent_fleet/engine/teammates.py), addressed by name. spawn_teammate stands one up from
its template (toolkits can pin its capabilities) and runs it in the background; check_teammate
reads the derived status and persisted outcome; message_teammate revives the standing session.
The pool key is teammate.{name}, so the same name always resumes the same conversation.
Consumption is push-style, not poll-in-conversation: set a harness Monitor on check_teammate
rather than re-checking it from inside the conversation. AGENT_FLEET_NOTIFY_COMMAND configures a
Stop-hook shell command that runs when a teammate's run finishes, receiving Claude Code's
hook-input JSON on stdin — the payload identifies the finished session.
Guarded Codex worker
Install and authenticate the Codex CLI once:
codex --version
codex loginEvery Claude fleet run—including named subagents and emitted agent programs—gets codex_run by
default. The tool accepts a self-contained prompt, an absolute canonical Git worktree root, a
read-only or workspace-write sandbox, a supported Codex model, reasoning effort,
timeout, and an optional prior thread UUID. It returns the final message, thread UUID, commands
observed in Codex JSONL, token usage, duration, and bounded failure detail.
Fresh prompts travel over stdin. Codex's documented non-interactive resume form requires a positional prompt, so resumed prompts are capped at 64,000 UTF-8 bytes for macOS process-argument portability; avoid putting secrets in a resume prompt because local process listings can expose command arguments.
The secure defaults are intentional:
cwdmust stay under an absolute, existing operator-allowlisted directory. An empty root list uses the fleet process working directory, except when that directory is the filesystem root or user home; set an explicit narrower allowlist in those cases.read-onlyis the default and Codex receives--ask-for-approval never.workspace-writeis disabled until explicitly enabled, and then accepts only a clean, detached linked Git worktree.the wrapper never uses
--skip-git-repo-check, never invokes a shell, ignores user Codex config for the automated run, explicitly treats the worktree as untrusted so project.codex/config, hooks, rules, and MCP servers do not load, and pins adjacent controls: no command network, web search, extra writable or temporary roots, hooks, apps, remote plugins, nested agents, login shells, or broad command-environment inheritance.runtime/output are bounded, the whole child process group is terminated on macOS and Linux, and common API/service credentials are removed from the Codex process environment.
the pool MCP does not expose a direct Codex endpoint; the running Claude agent is the caller.
Configure the boundary with environment variables:
AGENT_FLEET_CODEX_ENABLED=true
AGENT_FLEET_CODEX_ALLOWED_ROOTS='["/absolute/path/to/repos","/absolute/path/to/worktrees"]'
AGENT_FLEET_CODEX_ALLOW_WORKSPACE_WRITE=false
AGENT_FLEET_CODEX_MAX_TIMEOUT_SECONDS=3600For implementation workers, set AGENT_FLEET_CODEX_ALLOW_WORKSPACE_WRITE=true, create a detached
linked worktree under an allowed root, and pass that exact worktree root to codex_run. Disabling
AGENT_FLEET_CODEX_ENABLED removes the server and tool grant entirely.
Develop
uv sync --extra api
uv run pytest
uv run ruff check
uv run mypy src
make coverage # test coverage, printed to the terminalDetails: docs/OVERVIEW.md · docs/pipeline.md · docs/catalog-boundary.md · docs/live-smoke.md
Coverage
Available Tools
10 toolscreate_agentA
Assemble an agent for a task and store it in the pool under agent_key, returning the
stored entry — the create/update entry point an orchestrating agent uses to stand up a new
pooled agent (or re-assemble an existing one).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Optional display name; auto-slugged from the task when omitted. | |
| tags | No | Optional routing tags to narrow recall and to label the stored entry. | |
| task | Yes | What the generated agent should do — the job it is being built to perform. | |
| team | No | Name of the team that owns the generated agent. | default |
| model | No | Which model the agent runs on; `inherit` defers to the caller's model. | inherit |
| pinned | No | Capability ids to force into the selection regardless of relevance score. | |
| agent_key | Yes | Stable external identifier for the pooled agent a caller manages — assign your own scheme (a ticket id, a slug, a UUID, anything meaningful to your use case). The pool's logical lookup key; distinct from the human-readable display name, and distinct from the harness's per-dispatch `AgentId`. | |
| reset_session | No | When True, mint a fresh session UUID even if the id already exists. | |
| system_prompt | No | A full system-prompt override; when omitted, one is templated from the task and the selected tools/skills. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| cwd | Yes | |
| name | Yes | The agent's unique name — lowercase letters, digits, and dashes. |
| spec | Yes | The canonical agent definition the pipeline assembles and the Claude Agent SDK emitter renders into a runnable program. `tools` and `mcp_servers` are kept separate here; the merged SDK tool-grant is derived at emission by `engine.render.tool_grant`. |
| agent_key | Yes | Stable external identifier for the pooled agent a caller manages — assign your own scheme (a ticket id, a slug, a UUID, anything meaningful to your use case). The pool's logical lookup key; distinct from the human-readable display name, and distinct from the harness's per-dispatch `AgentId`. |
| created_at | Yes | |
| session_id | Yes | The Claude Agent SDK session UUID a pool entry pins and resumes — a lowercase-hex UUID, generated internally, never the human-readable pool name. |
| updated_at | Yes |
TDQS
A3.7/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions storing and returning an entry, and implies upsert behavior (re-assemble existing). However, it lacks disclosure of important behavioral traits such as authentication requirements, rate limits, side effects of overwriting, or details on what happens when agent_key exists (update vs error).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is informative and front-loaded with the main action. It could be slightly more concise but is not overly verbose. Effective for its length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (9 parameters, create/update semantics) and the presence of an output schema (not shown but indicated as true), the description adequately covers the tool's role as the pool entry point, storage under agent_key, and return of stored entry. Some minor gaps remain (e.g., explicit mention of idempotency), but overall sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter is already well-documented. The tool description adds high-level context but does not significantly enhance understanding of individual parameters beyond what the schema provides. Thus, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (assemble and store) and the resource (agent in the pool). It distinguishes itself from sibling tools by being the only create/update entry point, with explicit mention of 'create/update' and 'stand up a new pooled agent or re-assemble an existing one'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates when to use it (to create or update a pooled agent) and implies it is for orchestration. It does not explicitly state when not to use it, but the sibling tools (list, get, delete, run) provide clear alternatives for other operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
delete_agentA
Remove the pooled entry stored under agent_key.
This is also the legitimate dismissal path for a teammate: deleting its teammate.* entry
discards its standing conversation, and the next run_teammate call
re-creates it fresh from its roster template. No guard against the teammate namespace here —
unlike create_agent/run_agent, dismissal is intentional deletion, not accidental bypass.
Dismissing a teammate with a live run discards that run's record along with the entry, and the
still-running background task dies unrecorded when it eventually finishes or fails.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| agent_key | Yes | Stable external identifier for the pooled agent a caller manages — assign your own scheme (a ticket id, a slug, a UUID, anything meaningful to your use case). The pool's logical lookup key; distinct from the human-readable display name, and distinct from the harness's per-dispatch `AgentId`. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
A4.6/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description fully carries the burden. It discloses that deleting a teammate entry discards its conversation, and if a live run exists, the run's record is discarded and the background task dies unrecorded. It also explicitly states there is no guard against the teammate namespace, providing full behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise but packed with useful information. It starts with the core action and then explains implications. While each sentence adds value, there is slight redundancy in explaining the teammate dismissal concept across sentences; still, it is well-structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the tool (deletion with cascading effects on teammates and runs), the description is complete. It covers the main action, the side effects on conversations and runs, and the behavioral contrast with sibling tools. An output schema is indicated, so return values are not needed in the description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides a detailed description of agent_key with pattern, examples, and meaning. The description adds minimal additional value beyond restating that it is the key for the pooled entry. With 100% schema coverage, the baseline is 3, and the description does not significantly enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool removes a pooled entry stored under agent_key, and further clarifies it's the legitimate dismissal path for a teammate. The verb 'Remove' and the resource 'pooled entry' make the purpose unambiguous, and it distinguishes from sibling tools like create_agent or run_agent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance on when to use this tool (dismissing a teammate), what happens as a result (discards standing conversation, next run recreates fresh), and contrasts with create_agent/run_agent to highlight that dismissal is intentional deletion, not accidental bypass. This helps the agent choose the correct tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
find_agentsA
Rediscover pooled agents by re-describing the problem, ranked most-relevant first —
the fuzzy path for when the exact agent_key isn't at hand.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Most matching catalog items the search step may return. | |
| query | Yes | What the generated agent should do — the job it is being built to perform. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
A3.9/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries burden. Mentions fuzzy search and relevance ranking, but lacks detail on edge cases (e.g., no match, algorithm specifics). 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with clear structure, though slightly verbose with em dash and 'fuzzy path' metaphor. Front-loaded with action and scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given low parameter count and presence of output schema, description is sufficient for basic usage. Could mention output shape or ranking details but not necessary for understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear parameter descriptions. Description reinforces query purpose but adds minimal new information beyond what schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool rediscovers agents by description, with ranking and fuzzy matching. Distinguishes from sibling tools like get_agent (exact key) and list_agents (listing all).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'when the exact agent_key isn't at hand', providing clear context for when to use. Doesn't explicitly list when not to use, but implies alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_agentA
Return the pooled entry stored under agent_key, or None when the pool holds no such entry.
A safe probe: returns None rather than raising when the id is absent, so an orchestrating agent can check existence without handling an error.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| agent_key | Yes | Stable external identifier for the pooled agent a caller manages — assign your own scheme (a ticket id, a slug, a UUID, anything meaningful to your use case). The pool's logical lookup key; distinct from the human-readable display name, and distinct from the harness's per-dispatch `AgentId`. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
A4.5/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, description discloses key behavior: returns None on missing key. No mention of side effects or permissions, but sufficient for a simple get.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with core purpose, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With output schema present, description completes the picture: what returns, behavior on absence, safe usage. Sibling context suffices.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed description of agent_key. Description adds context that missing key returns None, enhancing parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it returns a pooled entry by agent_key, with None on absence. Distinguishes from siblings like create_agent, list_agents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly notes it is a safe probe for existence checking without error handling. Does not elaborate on when not to use or contrast with siblings, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_runA
Return one run record by its run_id, or None when the pool holds no such run.
A safe probe, mirroring get_agent: returns None rather than raising when the id is
absent, so an orchestrating agent can check existence without handling an error.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes | Identifier for one invocation of a pooled agent — a lowercase-hex UUID minted per run, distinct from the session UUID: a run is a single dispatch, a session is the resumable conversation a run continues. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
A4.5/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description discloses key behavior: returns None instead of raising exceptions and is a safe, read-only operation. Additional details like idempotency or side effects are not covered, but the core behavior is clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first states core purpose, second adds nuance about safety and comparison with get_agent. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with an output schema, the description covers purpose, behavior, and usage context completely. The agent has enough information to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema itself provides a detailed description of run_id including its relationship to session. The tool description does not add extra parameter information beyond referencing run_id, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns one run record by run_id, and specifies the None return behavior when the run doesn't exist. This distinguishes it from siblings like list_runs or run_agent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly describes the tool as a 'safe probe' mirroring get_agent, meant for existence checking without error handling. This guides an agent on when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_agent_runsA
List every agent that ran within one run and the real, resumable session id each was given.
This is how an orchestrating agent discovers the independently-resumable session_id of every
agent — the run's main/supervisor agent and any subagents it dispatched — that participated in a
specific run_id (obtained from list_runs, get_run, or a
RunOutcome). Each captured session id can then be used to resume that one agent's conversation
on its own, independently of the others, later.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes | Identifier for one invocation of a pooled agent — a lowercase-hex UUID minted per run, distinct from the session UUID: a run is a single dispatch, a session is the resumable conversation a run continues. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
A4.2/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It explains the output (real, resumable session IDs) and implies read-only behavior, but does not explicitly state safety, side effects, or permissions. Adequate but could be more explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is clear and front-loaded with the core purpose. Second paragraph adds valuable usage context, though slightly wordy. No wasted sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple parameter set and existence of output schema, the description is complete. It explains the tool's role in the workflow and references sibling tools, providing sufficient context for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed description of run_id. The description adds context by explaining why run_id is needed and how to obtain it, going beyond the schema's format specification.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list' and the specific resource: every agent that ran within one run and their session ID. It distinguishes from sibling tools like list_runs by explaining that it discovers resumable session IDs from a given run_id.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use this tool: after obtaining a run_id from list_runs, get_run, or RunOutcome, to get session IDs for resuming agents. It does not mention when not to use it, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_agentsB
Return every pooled agent, most-recently-updated first.
Returns: Every stored pool entry, newest-updated first.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
B3.3/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the ordering behavior but lacks other important behavioral details such as read-only nature, pagination, rate limits, or access control. With no annotations, the description carries the full burden and 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief but contains repetition—the second sentence essentially restates the first. It is not overly long but wastes space; a single sentence would be more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list-all tool with no parameters and an output schema, the description covers the basic purpose and ordering. However, it lacks context about scope (e.g., user-specific vs. global) and does not clarify how it differs from 'find_agents'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, and schema description coverage is trivially 100%. The baseline for zero parameters is 4, and the description adds no unnecessary detail about parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Return every pooled agent' with a specific verb and resource, and includes the ordering 'most-recently-updated first', which distinguishes it from sibling tools like 'find_agents' that likely support filtering.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as 'find_agents' or 'list_agent_runs'. The description implies it returns all agents without filters, but does not explicitly state use cases or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_findingsA
Return the pooled agent's findings oldest-first — the assembled-document reading order.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | No | When given, return only the findings recorded within that run; None returns all. | |
| agent_key | Yes | Stable external identifier for the pooled agent a caller manages — assign your own scheme (a ticket id, a slug, a UUID, anything meaningful to your use case). The pool's logical lookup key; distinct from the human-readable display name, and distinct from the harness's per-dispatch `AgentId`. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
A3.5/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context about the ordering and reading order, which is beyond what annotations (absent) would provide. However, it does not disclose other aspects like idempotency, pagination, or error conditions, leaving moderate gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently conveys the core purpose and ordering. It front-loads the verb and resource, with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists, the description does not need to detail return structure. However, it lacks explanation of key concepts like 'assembled-document reading order' and whether results are paginated, leaving some ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides full descriptions for both parameters (run_id and agent_key) with 100% coverage. The description does not add any extra meaning beyond the schema, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Return', the resource 'pooled agent's findings', and the ordering 'oldest-first' with the notion of 'assembled-document reading order'. It distinguishes this tool from siblings like list_agent_runs and get_run by focusing on findings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as get_run or list_agent_runs. There is no mention of prerequisites, context, or exclusions, leaving the agent without decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_runsA
Return every run recorded for agent_key, most-recently-started first.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| agent_key | Yes | Stable external identifier for the pooled agent a caller manages — assign your own scheme (a ticket id, a slug, a UUID, anything meaningful to your use case). The pool's logical lookup key; distinct from the human-readable display name, and distinct from the harness's per-dispatch `AgentId`. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
A3.8/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behaviors. It states ordering but omits details like pagination, error handling for unknown agent_key, permission requirements, or whether it is read-only (implied but not explicit). The sorting order is a positive disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that conveys the core action, resource, and ordering with no unnecessary words. It is appropriately front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 parameter) and the presence of an output schema, the description is largely complete. It could be improved by mentioning potential pagination or clarifying its relation to list_agent_runs, but overall provides sufficient context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description does not add additional meaning beyond the schema's field description for agent_key; it merely references the parameter. Minimal value added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Return') and resource ('every run recorded for agent_key'), and specifies ordering ('most-recently-started first'). It clearly distinguishes from sibling tools like get_run (single run) and list_agent_runs (possibly different scope).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing runs by agent_key but provides no explicit guidance on when to use this vs siblings like list_agent_runs, or when not to use it. No exclusions or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
run_agentA
Run the pooled agent live and record every agent that participates. The entry's first-ever run starts a fresh session; later runs resume it. Requires the claude CLI at runtime.
Every run is granted the full capability set — for the main agent and, when named, for each
dispatched subagent: fan-out subagents (resolved from their own pool entries and wired in via
with_subagents), the run-scoped findings-writer (with_findings_tool), and dynamic capability
acquisition (with_acquire_tool). The findings tool needs the run id at wiring time, so the run
is started here and its id handed to run_with_capture rather than minted inside it.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| task | Yes | What the generated agent should do — the job it is being built to perform. | |
| agent_key | Yes | Stable external identifier for the pooled agent a caller manages — assign your own scheme (a ticket id, a slug, a UUID, anything meaningful to your use case). The pool's logical lookup key; distinct from the human-readable display name, and distinct from the harness's per-dispatch `AgentId`. | |
| resume_agent_id | No | When set, continue one specific previously-dispatched subagent (its `AgentId`, captured from an earlier `RunOutcome.agent_runs[i].agent_id`) rather than just re-prompting the main agent: this run resumes the main session, is granted the harness's `SendMessage` tool (`with_agent_resume`), and its literal turn wraps `task` as `"Resume agent {id} and now: {task}"` — while the run record still logs `task`. It composes with `subagent_agent_keys`, since the resumed turn may dispatch further subagents too. | |
| subagent_agent_keys | No | A subagent name → pooled `agent_key` mapping; each referenced entry's spec is wired in as a dispatchable subagent that also carries the findings and acquire tools. Empty runs the agent solo. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| run | Yes | One invocation of a pooled agent — appended when a run starts and stamped when it finishes. Distinct from `PoolEntry`'s "current state per problem" role: an entry has many runs over its life. `finished_at` and the outcome fields (`output`, `structured_output`, `total_cost_usd`, `error`) stay None while the run is in flight, and the outcome fields stay None afterward too if the run finished without a captured outcome. `error` is set instead of the outcome fields when the run raised rather than completed. |
| output | Yes | The collected assistant text of a finished run, persisted on its record; text over 200000 characters is truncated to that bound. |
| agent_runs | Yes | |
| total_cost_usd | No | |
| structured_output | No |
TDQS
A4.6/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavioral traits: recording participants, session start/resume, full capability set, findings tool wiring, and resume_agent_id behavior. It covers both simple and complex runs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is information-dense and front-loaded with the core purpose. While it is a single paragraph, it is well-structured and every sentence contributes meaning. Could be slightly more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 parameters, nested objects, output schema), the description covers session lifecycle, tool wiring, and parameter interactions comprehensively. It addresses edge cases like resume and subagents.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value by explaining how parameters like resume_agent_id and subagent_agent_keys interact with the overall run mechanism, beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool runs a pooled agent, records participant agents, and distinguishes between first-run and resumed sessions. It includes a requirement (claude CLI) and differentiates from sibling tools like create_agent and list_agents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (to run a pooled agent), describes session behavior, and outlines the granted capabilities. It does not explicitly exclude alternative tools, but the context makes usage clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
TDQS
A4.1/5.0
Disambiguation5/5
Each tool targets a distinct operation: agent CRUD, run listing, run execution, and findings retrieval. No two tools have overlapping purposes, and descriptions clearly differentiate them.
Naming Consistency5/5
All tool names follow a consistent verb_noun pattern using snake_case, e.g., create_agent, list_agents, get_run. Verbs are imperative and clear, with no mixed conventions.
Tool Count5/5
10 tools cover the agent fleet management domain without being excessive or insufficient. Each tool serves a clear purpose in the lifecycle of agents and runs.
Completeness4/5
The tool surface covers core agent and run operations (create, read, delete, search, run, list runs), but lacks explicit run modification or cancellation capabilities, which is a minor gap.
Maintenance
ActivityMaintained
ResponsivenessSyncing
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
MCP server for building and testing AI agents with multi-model experimentation and insights.
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Related MCP Servers
- FlicenseAqualityFmaintenanceMCP server that exposes 300+ AI agents as tools via a single API key. Supports listing agents, invoking any agent with chat-completion style messages, checking agent health, and retrieving platform statistics.53
- AlicenseNot gradedqualityBmaintenanceMCP server that enables agents to dynamically switch between multiple AI models (OpenAI, Anthropic, Google, etc.) with unified protocol-driven configuration and capability discovery.Apache 2.0
- AlicenseNot gradedqualityDmaintenanceAn MCP server that wraps the Claude Agent SDK, enabling Claude-powered queries, coding tasks, web search, and customizable agent execution using OAuth without an API key.21MIT
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Magic-Man-us/claude-sdk-agent-fleet'
If you have feedback or need assistance with the MCP directory API, please join our Discord server