The external-agent-mcp server provides an MCP interface to delegate coding tasks to external CLI agents (Cursor, Gemini, Claude), manage asynchronous jobs, and run deterministic quality fixes.
Delegate Tasks: Create one or more async jobs targeting external CLI agents. Supports parallel execution (up to 50 tasks), two modes (analysis for read-only inspection, sandbox_patch for isolated code changes in git worktrees), model selection, file focusing, custom context, and per-task overrides.
Monitor Job Status: Poll lifecycle states (queued, running, succeeded, failed, timed_out, cancelled, orphaned) and view stdout/stderr tails. Lists recent jobs if no specific job ID is provided.
Retrieve Job Results: Fetch full result text, command metadata, exit status, log paths, and for sandbox patches: result.md, diff.patch, diff.stat, and changed file lists.
Search Job History: Query past jobs by repo path, provider, model, mode, status, date range, or free-text substring, with pagination support.
Cancel Jobs: Stop any queued or running jobs by ID.
Clean Up Jobs: Remove logs, artifacts, and sandbox worktrees for terminal jobs; use force: true for non-terminal jobs.
Check Agent Status: Verify provider CLI binaries are installed and report capability metadata (e.g., supports_analysis, supports_sandbox_patch, safe_write_mode).
Run Quality Fixes: Execute allow-listed Ruff commands (ruff_format, ruff_safe_fix, ruff_check, ruff_unsafe_fix) over a bounded file set without spending LLM tokens, with diff stats and unsafe fix opt-in.
Provides tools to run Ruff formatter and linter for automated code formatting and safe fixes.
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., "@external-agent-mcp analyze code with gemini for performance issues"
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.
Local stdio MCP runtime that lets Codex delegate work to installed external CLI coding agents. Codex starts asynchronous jobs through one MCP call, then polls for status, free-form results, logs, and sandbox patch artifacts.
The server is dependency-free Node.js and speaks MCP over line-delimited JSON-RPC on stdio.
Initial provider adapters:
Cursor Agent via CURSOR_AGENT_BIN
Gemini CLI via GEMINI_BIN
Claude Code via CLAUDE_BIN
Model selection is caller-controlled with the model argument. The MCP server
does not hardcode routing logic such as "simple task uses X, complex task uses
Y".
Related MCP server: peer-cli-mcp
delegate_tasksCreates one or more async jobs.
Required arguments:
repo_path: absolute repository/workspace path
provider: cursor, gemini, or claude
tasks: array of task strings or task objects
Common optional arguments:
mode: analysis or sandbox_patch; defaults to analysis
model: provider-specific model override
files: focus files under repo_path
extra_context: additional background
timeout_sec: defaults to 600, capped at 1800
max_output_chars: defaults to 30000, capped at 100000
base_ref: git ref for sandbox_patch; defaults to HEAD
Task objects may override provider, model, mode, files,
extra_context, timeout_sec, max_output_chars, and base_ref.
job_statusReturns job lifecycle state and stdout/stderr tails. Status values are:
queued
running
succeeded
failed
timed_out
cancelled
orphaned
If no job_id or job_ids are supplied, recent jobs are returned.
job_resultReturns the external agent's free-form result text plus MCP-managed metadata:
command metadata and exit status
stdout/stderr log paths
result.md
diff.patch, diff.stat, and changed files for sandbox_patch
search_jobsSearches historical jobs by lightweight metadata and previews. This is the
stable history lookup interface; full text and patch artifacts should still be
read with job_result.
Supported filters:
repo_path: exact repository path
provider: cursor, gemini, or claude
model: exact model string
mode: analysis or sandbox_patch
status: any of queued, running, succeeded, failed, timed_out,
cancelled, or orphaned
created_after / created_before: ISO timestamps
query: case-insensitive substring search over title, task, result preview,
paths, provider/model/mode, and focused files
limit: defaults to 20, capped at 100
cursor: opaque pagination cursor from a previous response
The response returns job summaries, previews, hashes, and artifact paths. It does not return large stdout, stderr, result, or patch bodies.
cancel_jobsCancels queued or running jobs.
cleanup_jobsRemoves terminal job logs/artifacts and associated sandbox worktrees. Use
force: true only when cleaning non-terminal jobs intentionally.
agent_statusChecks provider binaries and reports capability metadata:
supports_analysis
supports_sandbox_patch
supports_models
safe_write_mode
quality_fixRuns allow-listed deterministic quality commands over a bounded file set. This path is for mechanical fixes and does not spend LLM agent tokens.
Default commands:
ruff_format: ruff format <files>
ruff_safe_fix: ruff check --fix <files>
Additional commands:
ruff_check: ruff check <files>
ruff_unsafe_fix: ruff check --fix --unsafe-fixes <files>; requires
allow_unsafe_fixes: true
Jobs are persisted under:
~/.cache/external-agent-mcp/jobsOverride with:
EXTERNAL_AGENT_JOB_ROOT=/path/to/jobsEach job directory contains:
job.json
events.jsonl
stdout.log
stderr.log
result.md
diff.patch
diff.stat
If the MCP server restarts, non-terminal jobs from the previous process are
marked orphaned. Completed job artifacts remain readable.
The current storage implementation is FileJobStore: metadata is read from
job.json, events are appended to events.jsonl, and large artifacts remain as
plain files. search_jobs is intentionally defined above this storage layer so
a future SQLite-backed index can replace the file scan without changing the MCP
tool contract.
New jobs include stable metadata for history and future caching:
schema_version
repo_head
task_hash
prompt_hash
duration_ms
result_preview
mode: "sandbox_patch" requires a git repository. The server creates an
isolated git worktree under the job directory, runs the external agent there,
and then captures git diff --binary and git diff --stat.
The original repository is not modified by agent writes.
Provider write policy is conservative:
Cursor sandbox patch is marked experimental and is launched without
--force or --yolo.
Gemini uses --approval-mode auto_edit.
Claude uses --permission-mode acceptEdits with a restricted tool list.
The server rejects adapter commands that include --force, --yolo, or
bypass-permission flags.
Add this to ~/.codex/config.toml or a trusted project .codex/config.toml:
[mcp_servers.external_agent]
command = "node"
args = ["/path/to/external-agent-mcp/src/server.mjs"]
startup_timeout_sec = 10
tool_timeout_sec = 900
[mcp_servers.external_agent.env]
CURSOR_AGENT_BIN = "/path/to/cursor"
GEMINI_BIN = "/path/to/gemini"
CLAUDE_BIN = "/path/to/claude"
RUFF_BIN = "ruff"
EXTERNAL_AGENT_ALLOWED_ROOTS = "/path/to/workspace:/path/to/another-workspace"
EXTERNAL_AGENT_MAX_CONCURRENCY = "2"After changing MCP config, refresh/restart Codex or start a new thread so the new tool surface is loaded.
{
"provider": "cursor",
"model": "your-model-name",
"repo_path": "/path/to/your-repo",
"mode": "analysis",
"tasks": [
"Map the request lifecycle from the API handler to the service layer. Return concise findings with file paths.",
"Audit authentication and permission boundaries. Return risks and missing tests."
],
"timeout_sec": 900
}{
"provider": "claude",
"repo_path": "/path/to/your-repo",
"mode": "sandbox_patch",
"tasks": [
{
"task": "Fix the focused Ruff SIM102 issue and summarize the patch.",
"files": ["src/example/path.py"]
}
]
}Then call job_status until terminal and job_result to inspect the free-form
result, logs, and patch path.
{
"repo_path": "/path/to/your-repo",
"provider": "cursor",
"model": "your-model-name",
"mode": "analysis",
"status": ["succeeded", "failed"],
"query": "request lifecycle",
"limit": 20
}{
"repo_path": "/path/to/your-repo",
"files": ["src/example/path.py"],
"commands": ["ruff_format", "ruff_safe_fix"],
"timeout_sec": 120,
"max_changed_files": 10
}npm testCheck configured external CLI agent binaries and report provider capability metadata.
| Name | Required | Description | Default |
|---|---|---|---|
| provider | No | External agent CLI provider. | |
| timeout_sec | No | Per-provider timeout in seconds. Defaults to 10. |
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 implies a read-only operation but does not explicitly state non-destructiveness, authentication needs, or side effects. This is insufficient for an agent.
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?
A single sentence with 11 words, front-loaded with the main action. No redundancy or fluff; every word is meaningful.
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 low complexity (2 optional params, no output schema), the description provides the overall purpose. However, it omits details about the return format of 'provider capability metadata', which would help an agent utilize the output.
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 clear descriptions for both parameters (provider enum, timeout_sec default). The description adds context but no new parameter details beyond the schema, earning the baseline 3.
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 specific verbs 'check' and 'report' along with the resource 'external CLI agent binaries' and output 'capability metadata'. It clearly distinguishes this tool from siblings like 'analyze_code' or 'cancel_jobs' which are unrelated.
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 does not specify when to use this tool versus alternatives or any prerequisites. While siblings are different, the lack of explicit guidance lowers the score from 4 to 3.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deprecated compatibility wrapper around delegate_tasks for one read-only analysis job. Prefer delegate_tasks + job_result.
| Name | Required | Description | Default |
|---|---|---|---|
| task | Yes | Concrete read-only code analysis task for the external agent. | |
| files | No | Optional repo-relative or absolute file paths to focus on. Absolute paths must stay under repo_path. | |
| model | No | ||
| provider | Yes | External agent CLI provider. | |
| repo_path | Yes | Absolute path to the repository or workspace to analyze. | |
| timeout_sec | No | Timeout in seconds. Defaults to 600; capped at 1800. | |
| extra_context | No | ||
| include_stderr | No | Include stderr in the returned JSON payload. Defaults to true. | |
| max_output_chars | No | Maximum returned output characters. Defaults to 30000; capped at 100000. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It states the tool is read-only and a wrapper around delegate_tasks, which implies no destructive side effects. However, it does not elaborate on other behavioral traits like error handling or output format, but the read-only hint is valuable.
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 long, no wasted words. It front-loads the deprecation status and the key purpose, then provides the recommended alternative.
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 that this is a deprecated compatibility wrapper, the description is complete: it tells the agent the tool's role, its read-only nature, and directs to the superior alternative. The 9 parameters and lack of output schema are compensated by the schema's own descriptions and the deprecation context.
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 78%, so the schema already documents most parameters. The description adds minimal parameter-specific meaning, only hinting that 'task' is a read-only analysis task. It does not significantly augment the schema's 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 is a deprecated compatibility wrapper for one read-only analysis job, distinguishing it from the sibling delegate_tasks. The verb 'analyze_code' and noun 'code' are specific, and the description directly addresses 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?
The description explicitly advises to prefer 'delegate_tasks + job_result' as an alternative, and indicates deprecation. This gives clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cancel queued or running asynchronous jobs.
| Name | Required | Description | Default |
|---|---|---|---|
| job_ids | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses that it cancels queued/running jobs (mutation), but omits permissions, reversibility, or 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?
Single sentence with no wasted words, but it is too minimal; sacrifices completeness for brevity.
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?
Lacks return value, side effects, examples, or any context beyond the basic action. Inadequate for a tool with no annotations and no output schema.
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 0% and description adds no meaning beyond parameter name. The 'job_ids' parameter is not explained in terms of format or source.
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 action ('Cancel') and resource ('queued or running asynchronous jobs'), but does not differentiate from sibling tools like cleanup_jobs which might have similar behavior.
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?
No guidance on when to use this tool versus alternatives like job_status or cleanup_jobs. Lacks context for appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove terminal job logs/artifacts and associated sandbox worktrees. Non-terminal jobs require force=true.
| Name | Required | Description | Default |
|---|---|---|---|
| force | No | Allow cleanup of non-terminal jobs after sending SIGTERM. | |
| job_ids | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description effectively conveys key behaviors: it removes artifacts and worktrees, and for non-terminal jobs it sends SIGTERM. It discloses the destructive nature and the need for force flag, though it could be more explicit about irreversibility.
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, no unnecessary words, and front-loads the core purpose ('Remove terminal job logs/artifacts...'). Every sentence contributes meaningful 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 tool with 2 parameters and no output schema, the description covers the main behavior, the force condition, and the scope of cleanup. It lacks details about return values or side effects on job state, but these are not critical given the absence of an output schema.
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 50% (only 'force' has a description). The description adds value by clarifying when 'force' is required ('Non-terminal jobs'), which goes beyond the schema's mention of SIGTERM. However, it adds no extra context for 'job_ids' beyond the schema structure. Overall, it moderately compensates for the partial schema coverage.
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 ('Remove') and clearly identifies the resource ('terminal job logs/artifacts and associated sandbox worktrees'). It also implicitly distinguishes from sibling tools like 'cancel_jobs' and 'job_status' by focusing on post-termination cleanup.
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 conditional usage cue ('Non-terminal jobs require force=true') but does not explicitly compare this tool to alternatives like 'cancel_jobs' or specify when not to use it. 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.
Create one or more asynchronous external-agent jobs. Use job_status and job_result to inspect completion and artifacts.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | analysis runs read-only in the repo; sandbox_patch runs in an isolated git worktree. | |
| files | No | Optional repo-relative or absolute file paths to focus on. Absolute paths must stay under repo_path. | |
| model | No | Provider-specific model override chosen by the caller. | |
| tasks | Yes | ||
| base_ref | No | Git ref used for sandbox_patch worktree creation. Defaults to HEAD. | |
| provider | Yes | External agent CLI provider. | |
| repo_path | Yes | Absolute path to the repository/workspace. | |
| timeout_sec | No | Timeout in seconds. Defaults to 600; capped at 1800. | |
| extra_context | No | ||
| max_output_chars | No | Maximum returned output characters. Defaults to 30000; capped at 100000. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions 'asynchronous' and suggests non-blocking behavior, but it does not disclose side effects, authentication needs, rate limits, or the difference between modes (analysis vs sandbox_patch), which are partially covered 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?
The description is two sentences, directly states the purpose, and front-loads the verb and resource. Every sentence earns its place with no waste.
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, the description mentions job_status and job_result for inspecting results, but it lacks details on return values, mode behavior, or provider selection. For a tool with 10 parameters, it is somewhat 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?
Schema coverage is 80%, so the schema already documents most parameters. The description adds no parameter-specific meaning beyond the schema, resulting in a baseline score of 3.
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 verb 'Create' and the resource 'asynchronous external-agent jobs', and it distinguishes from sibling tools like job_status and job_result by mentioning them for inspection.
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 implies usage for creating jobs and points to job_status/job_result for follow-up, but it does not explicitly contrast with alternatives like analyze_code or agent_status, nor does it provide when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read completed or in-progress job outputs, free-form result text, diff metadata, and artifact paths.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | No | ||
| job_ids | No | ||
| include_stderr | No | Include stderr text. Defaults to true. | |
| max_output_chars | No | Maximum returned output characters. Defaults to 30000; capped at 100000. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states the tool is for reading (non-destructive), but lacks details on permissions, rate limits, or handling of large outputs. The 'max_output_chars' parameter is documented in schema but not mentioned in description.
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 a single sentence that front-loads the main action and lists the output components. It is concise but could be better structured with separate clauses for different output types.
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 4 parameters, no output schema, and the complexity of reading job outputs (which may be large or varied), the description is too minimal. It omits details on result format, pagination, error handling, and default behaviors.
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 50% (2 of 4 parameters have descriptions). The description does not mention any parameters, adding no value beyond the schema. It fails to compensate for the gap in undocumented parameters.
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 'Read' and identifies the resource as 'completed or in-progress job outputs, free-form result text, diff metadata, and artifact paths.' It clearly distinguishes from sibling tools like 'job_status' (status only) and 'cancel_jobs' (cancellation).
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 does not provide any guidance on when to use this tool over alternatives, nor does it state prerequisites or exclusions. It merely states what it reads, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read asynchronous job status, including stdout/stderr tails. If no job_ids are supplied, returns recent jobs.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Recent job count when job_ids are omitted. Defaults to 20. | |
| job_id | No | ||
| job_ids | No | ||
| tail_chars | No | Number of trailing stdout/stderr characters to include. Defaults to 4000. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries burden. It discloses read-only intent and inclusion of tails, but does not describe side effects, authorization needs, or return format. 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?
Two sentences with no unnecessary words. Purpose is front-loaded, and every sentence adds value: first states main function, second explains conditional behavior.
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 4 optional parameters, no output schema, and the presence of sibling tools like job_result and search_jobs, the description is somewhat complete but lacks details on parameter interactions, error cases, and how it differs from related tools.
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 50% (limit and tail_chars have descriptions). Description adds context that job_ids triggers 'recent jobs' behavior, but does not explain job_id singular or interactions between parameters. Minimal added value over 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?
Description clearly states verb 'Read' and resource 'asynchronous job status', including tails. It mentions alternative behavior when no job_ids are supplied, which helps distinguish from some siblings like job_result, but does not explicitly name alternatives.
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?
Description implies usage by stating conditional behavior for recent jobs, but lacks explicit guidance on when to use this tool versus siblings like job_result, search_jobs, or cancel_jobs. No when-not-to-use or alternatives mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run deterministic allow-listed quality commands such as Ruff format and safe fixes over a bounded file set.
| Name | Required | Description | Default |
|---|---|---|---|
| files | No | Optional repo-relative or absolute file paths to focus on. Absolute paths must stay under repo_path. | |
| commands | No | Quality commands to run. Defaults to ruff_format and ruff_safe_fix. | |
| repo_path | Yes | Absolute path to the repository/workspace. | |
| timeout_sec | No | Timeout in seconds. Defaults to 120; capped at 900. | |
| allow_repo_wide | No | Allow running commands over the whole repo with target '.'. Defaults to false. | |
| max_output_chars | No | Maximum returned output characters. Defaults to 30000; capped at 100000. | |
| include_diff_stat | No | Include git diff --stat after commands. Defaults to true. | |
| max_changed_files | No | Maximum newly dirty files allowed. Defaults to 20; capped at 200. | |
| allow_unsafe_fixes | No | Required to run ruff_unsafe_fix. Defaults to false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It mentions 'deterministic' and 'bounded file set' but does not disclose that the tool modifies files, uses git diff, enforces timeouts, or has safety limits like max_changed_files. The schema covers some behavioral aspects, but the description itself is minimal.
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 a single sentence that efficiently communicates the core action and scope. It front-loads the key information without any filler. Every word serves a purpose.
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 has 9 parameters, no annotations, and no output schema, the description is too brief. It omits important behavioral details such as safety mechanisms (allow_repo_wide, max_changed_files), diff statistics, and timeouts, which are necessary for an agent to use the tool effectively.
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 baseline is 3. The description adds no additional meaning to any parameters; it only gives a general purpose. It does not elaborate on defaults, constraints, or parameter interactions beyond what the schema already provides.
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 runs deterministic allow-listed quality commands like Ruff format and safe fixes on a bounded file set. It uses a specific verb ('Run') and resource, and the examples differentiate it from sibling tools that handle code analysis or job management.
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 implies the tool is for applying automated quality fixes, but lacks explicit guidance on when to use it versus alternatives like analyze_code. No 'when-not-to-use' or mention of prerequisites is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search historical external-agent jobs by metadata and lightweight previews. Use job_result for full artifacts.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | ||
| limit | No | Maximum jobs to return. Defaults to 20; capped at 100. | |
| model | No | Optional exact model filter. | |
| query | No | Case-insensitive substring search over task/title/result preview/path metadata. | |
| cursor | No | Opaque pagination cursor returned by a previous search_jobs call. | |
| status | No | Optional status filter. Matches any listed status. | |
| provider | No | External agent CLI provider. | |
| repo_path | No | Optional exact repository path filter. | |
| created_after | No | Optional ISO timestamp lower bound for created_at. | |
| created_before | No | Optional ISO timestamp upper bound for created_at. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not explicitly state that the tool is read-only or non-destructive. The verb 'Search' implies a safe operation, but the description leaves behavioral traits (auth, rate limits, side effects) entirely implicit. With no annotations, more explicit disclosure would improve transparency.
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 extremely concise: two sentences with no unnecessary words. The first sentence directly states the action and scope, and the second provides actionable guidance. Every sentence 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 has 10 parameters, no output schema, and no annotations, the description is too sparse. It does not explain what 'lightweight previews' contain, how pagination works (cursor), or that search is case-insensitive over specific fields. While the schema fills some gaps, the description should provide a high-level overview of behavior and return structure.
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 90%, so the input schema already documents most parameters well. The description adds no parameter-specific details beyond saying it returns 'metadata and lightweight previews', which is not tied to individual parameters. Thus, the description provides minimal added value beyond 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 clearly states the verb 'Search' and the resource 'historical external-agent jobs', and specifies it returns metadata and lightweight previews. It distinguishes from sibling 'job_result' by directing users to that tool for full artifacts.
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 explicitly advises 'Use job_result for full artifacts', providing a direct pointer to an alternative. However, it does not address when to use this tool versus other siblings like 'agent_status' or 'cancel_jobs', so some context is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Most tools are clearly distinct, focusing on different aspects of job lifecycle (delegate, status, result, cancel, cleanup) and configuration. The deprecated analyze_code tool overlaps with delegate_tasks, creating minor ambiguity, but it's clearly marked deprecated.
All tool names follow a consistent snake_case verb_noun pattern (e.g., cancel_jobs, cleanup_jobs, delegate_tasks, job_status, quality_fix). There are no mixed conventions, making the set predictable for an agent.
With 9 tools, the server is well-scoped for its purpose of managing external agent jobs. Each tool serves a necessary function without superfluous additions, and the count balances coverage and simplicity.
The tool surface covers the main job lifecycle (create, status, result, cancel, cleanup) plus search, configuration check, and a specific quality fix. Minor gap: a dedicated list_jobs tool is missing, but job_status with no job_ids returns recent jobs, covering that need.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Run verified read-only code tools: quant diagnostics + agent-ops preflight, no source exposure.
Source-checked CLI guides and model-aware planning for Claude Code, Codex, and Grok Build.
Security reviews for coding agents: diffs checked against your org policy and live infrastructure.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/parkavenue9639/external-agent-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
