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., "@Agent Collaboration Orchestrator Submit a task to refactor the login module to use OAuth2"
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.
面向 TRAE Work + Codex 的多智能体协同开发桥接器。
这个项目提供一个 MCP bridge 和一个 TRAE skill，让你可以在 TRAE Work 桌面端或移动端发起项目任务，由 TRAE 先做项目粗分析、方案规划和简单修改，再把困难实现、复杂重构、测试补全等子任务交给 Codex 执行。TRAE 可以继续查看 Codex 任务状态、日志、产物、权限请求，并在需要时调整、终止或批准重试。
TRAE 主导流程：TRAE 作为项目第一入口，Codex 作为困难任务执行器。
MCP 工具集：提交任务、查看状态、读取日志、获取报告、查看产物、请求修订、取消任务。
移动端友好：提供 get_mobile_dashboard，便于 TRAE 移动端查看当前任务、产物数量和待处理权限请求。
产物扫描：Codex 执行结束后自动扫描项目新增/修改文件，并通过 list_artifacts 暴露给 TRAE。
权限重试机制：Codex 因沙箱/权限失败后，bridge 可生成权限请求；TRAE 批准后创建更高权限的重试任务。
共享工作空间：推荐统一使用 codex_trae_workspace，让桌面端、移动端、MCP bridge 和 Codex 看到一致路径。
可手动接管：未配置 Codex 自动执行命令时，bridge 仍会生成 prompt 文件，可手动交给 Codex。
Related MCP server: codex-worker-runtime
下面流程用于在你的电脑上做一次最小可用测试：让 TRAE 通过 MCP 调用 Codex，在测试项目里创建一个文件，然后用移动端友好的工具查看状态和产物。
New-Item -ItemType Directory -Force E:\codex_trae_workspace确保本项目位于：
E:\codex_trae_workspace\agent-collaboration-orchestratorcd E:\codex_trae_workspace\agent-collaboration-orchestrator
& 'C:\Program Files\nodejs\npm.cmd' install
& 'C:\Program Files\nodejs\npm.cmd' run buildWindows 下建议使用 .cmd 或 .exe 路径，不要直接使用可能被 PowerShell 拦截的 .ps1。
where.exe codex
& 'C:\path\to\codex.cmd' --help
& 'C:\path\to\codex.cmd' exec --help请把后续配置中的 CODEX_EXECUTOR_COMMAND 改成你自己的 .cmd 或 .exe 路径。
New-Item -ItemType Directory -Force E:\codex_trae_workspace\mcp-test-project
Set-Content -Encoding UTF8 E:\codex_trae_workspace\mcp-test-project\README.md "# MCP test project"将下面配置加入 TRAE 的 MCP/工具配置中。路径按你的电脑实际情况调整。
{
"mcpServers": {
"codex-task-bridge": {
"command": "node",
"args": [
"E:/codex_trae_workspace/agent-collaboration-orchestrator/dist/cli.js"
],
"env": {
"SANDBOX_ROOT": "E:/codex_trae_workspace",
"CODEX_EXECUTOR_COMMAND": "C:/path/to/codex.cmd",
"CODEX_EXECUTOR_ARGS": "exec --cd {projectRoot} --sandbox {sandbox} --ask-for-approval never -",
"EXECUTOR_TIMEOUT_MS": "1800000"
}
}
}
}复制以下目录到 TRAE 支持的 skills 目录，并在 TRAE 中启用该 skill：
E:\codex_trae_workspace\agent-collaboration-orchestrator\skills\trae-codex-workspace在 TRAE 中输入：
使用 trae-codex-workspace skill。
在 E:/codex_trae_workspace/mcp-test-project 中测试 Codex 协作。
请先调用 diagnose_environment 检查环境。
然后通过 submit_task 交给 Codex 一个最小任务：在项目根目录创建 hello-from-codex.txt，内容为 hello from codex。
完成后用 get_mobile_dashboard 查看状态，用 list_artifacts 查看产物。正常情况下，你应该看到：
diagnose_environment 显示 Node 正常，sandboxRoot 是 E:/codex_trae_workspace
submit_task 返回一个 taskId
get_mobile_dashboard 能看到任务状态
list_artifacts 至少包含：
.agent-bridge/tasks/<taskId>/prompt.md
hello-from-codex.txt
如果任务失败，让 TRAE 继续调用：
get_task_log
list_permission_requests根据日志判断是 Codex 命令路径、API/中转站、权限沙箱，还是 TRAE MCP 配置问题。
User
|
v
TRAE Work Desktop / Mobile
| 1. 粗读项目、制定方案、拆分任务
| 2. 简单任务由 TRAE 直接完成
|
v
agent-collaboration-orchestrator MCP bridge
| submit_task / get_mobile_dashboard / list_artifacts / ...
|
v
Codex executor
| 3. 执行困难实现或复杂修改
| 4. 输出日志、报告、产物
|
v
TRAE 验收、修订、终止或批准重试建议先创建一个协同工作空间，并把 bridge 和所有协同开发项目都放进去：
codex_trae_workspace/
agent-collaboration-orchestrator/
my-app/
another-project/推荐配置：
SANDBOX_ROOT 指向整个 codex_trae_workspace
每次提交任务时，projectRoot 指向具体项目目录，例如 E:/codex_trae_workspace/my-app
这样可以限制 Codex 的可写范围，并让 TRAE 桌面端/移动端看到一致的任务和产物路径。
git clone https://github.com/muanlin/agent-collaboration-orchestrator.git
cd agent-collaboration-orchestrator
npm install
npm run build要求：
Node.js >= 18
TRAE Work
Codex CLI、本地 Codex、中转站脚本，或任何可通过命令行启动的 Codex 执行入口
把本项目作为 MCP server 配置到 TRAE Work。路径请替换为你自己的本机路径。
{
"mcpServers": {
"codex-task-bridge": {
"command": "node",
"args": [
"E:/codex_trae_workspace/agent-collaboration-orchestrator/dist/cli.js"
],
"env": {
"SANDBOX_ROOT": "E:/codex_trae_workspace",
"CODEX_EXECUTOR_COMMAND": "C:/path/to/codex.cmd",
"CODEX_EXECUTOR_ARGS": "exec --cd {projectRoot} --sandbox {sandbox} --ask-for-approval never -",
"EXECUTOR_TIMEOUT_MS": "1800000"
}
}
}
}Windows 用户建议把 CODEX_EXECUTOR_COMMAND 指向 .cmd 或 .exe，避免 PowerShell 执行策略拦截 .ps1。
Variable | Required | Description |
| Recommended | Codex 允许访问的协同工作空间根目录。 |
| Required for auto execution | Codex 执行入口，例如 |
| Optional | Codex 启动参数模板。默认通过 stdin 传入 prompt。 |
| Optional | 默认模型名称，会写入任务 prompt 供执行器参考。 |
| Optional | Codex 子任务超时时间，默认 30 分钟。 |
CODEX_EXECUTOR_ARGS 支持这些占位符：
Placeholder | Meaning |
| Bridge task ID |
| 项目目录 |
| Bridge 生成的 prompt 文件 |
| 沙箱模式： |
| 模型名称 |
| 任务标题 |
{
"CODEX_EXECUTOR_COMMAND": "C:/path/to/codex.cmd",
"CODEX_EXECUTOR_ARGS": "exec --cd {projectRoot} --sandbox {sandbox} --ask-for-approval never -"
}Bridge 会把生成的 prompt 内容通过 stdin 传给 codex exec ... -，同时保留 prompt 文件供 TRAE 查看。
{
"CODEX_EXECUTOR_COMMAND": "powershell",
"CODEX_EXECUTOR_ARGS": "-File E:/scripts/run-codex-task.ps1 -Workspace {projectRoot} -PromptFile {promptFile} -Sandbox {sandbox}"
}如果不配置 CODEX_EXECUTOR_COMMAND，submit_task 仍会创建任务和 prompt 文件，但任务会停在 pending。
<projectRoot>/.agent-bridge/tasks/<taskId>/prompt.md你可以手动把该 prompt 交给 Codex 执行。
仓库提供了一个可放到 TRAE 中运行的 skill：
skills/trae-codex-workspace/SKILL.md安装方式：将整个 skills/trae-codex-workspace 目录复制到 TRAE 支持的 skills 目录中。
这个 skill 会指导 TRAE：
在 codex_trae_workspace 中定位或创建项目
先粗读项目并拆分简单任务/困难任务
自己完成简单任务
通过 MCP submit_task 把困难任务交给 Codex
用 get_mobile_dashboard 在移动端查看任务总览
用 list_artifacts 查看 prompt 和 Codex 修改过的文件
用 request_revision 调整方向
用 cancel_task 终止任务
用 list_permission_requests / resolve_permission_request 处理权限重试
Tool | Description |
| TRAE 提交困难任务给 Codex。 |
| 查询单个任务状态。 |
| 查看任务执行日志。 |
| 获取任务完成报告。 |
| 基于原任务创建修订任务。 |
| 取消 pending/running 任务。 |
| 查看 prompt 文件和 Codex 执行后新增/修改的文件。 |
| 查看任务列表，适合桌面端/移动端任务视图。 |
| 获取移动端一屏摘要：任务统计、最近任务、待处理权限请求。 |
| 查看因权限/沙箱失败生成的待审批请求。 |
| 批准或拒绝权限请求。批准后创建重试任务。 |
| 检查 Node、工作区和 Codex 执行器配置。 |
在 TRAE 中给项目任务时，可以使用类似指令：
在 codex_trae_workspace/my-app 中实现登录功能。
你先粗读项目，输出方案并拆分任务。
简单页面和文案由你直接处理。
认证状态管理、复杂表单校验和测试交给 Codex。
我会在移动端查看进度、产物，必要时调整或终止任务。TRAE 应提交给 Codex 的任务应包含：
项目背景
具体目标
修改范围
禁止修改的文件或行为
约束条件
验收标准
需要运行的验证命令
示例：
{
"title": "实现订单状态流转核心逻辑",
"projectRoot": "E:/codex_trae_workspace/my-app",
"sandbox": "workspace-write",
"prompt": "TRAE 已完成初步分析：当前项目使用 Express + Prisma。请实现订单状态流转的核心服务逻辑，范围限定在 src/services/order-state.ts 和相关测试。不要修改数据库 schema。要求覆盖 paid -> shipped -> completed，以及 cancelled 的非法流转保护。完成后运行 npm test -- order-state 并报告结果。",
"constraints": {
"doNotChange": ["prisma/schema.prisma", "package.json"],
"preferredFiles": ["src/services/order-state.ts", "src/services/order-state.test.ts"]
},
"acceptanceCriteria": {
"checks": [
"合法状态流转成功",
"非法状态流转抛出明确错误",
"相关测试通过"
]
}
}移动端优先使用 get_mobile_dashboard，它会返回：
当前任务总数
running / pending / completed / failed / cancelled 数量
最近任务摘要
每个任务的最近日志
产物数量
待处理权限请求
移动端展示建议：
总览：running 1，failed 1，待审批 1
任务：
- 实现 auth service core：failed，产物 2，待审批 1
- 修复 UI 文案：completed，产物 3
待处理：permission-request-id，需要更高沙箱重试list_artifacts 会返回：
bridge 生成的 prompt 文件
Codex 执行后新增的文件
Codex 执行后修改的文件
产物扫描会忽略常见噪声目录：
.git
.agent-bridge
node_modules
dist
build
out
coverage
.next
.nuxt
.cache
.turbo
.vite
.parcel-cacheTRAE 桌面端/移动端不能直接点击 Codex CLI 的交互式权限弹窗。Bridge 采用更适合移动端的方式：
Codex 以非交互模式运行，例如：
codex exec --cd {projectRoot} --sandbox workspace-write --ask-for-approval never -如果 Codex 因权限或沙箱限制失败，bridge 会尝试识别错误并生成权限请求。
TRAE 用 list_permission_requests 或 get_mobile_dashboard 查看待审批请求。
用户批准后，TRAE 调用 resolve_permission_request。
Bridge 创建一个更高权限的重试任务。
批准示例：
{
"requestId": "permission-request-id",
"decision": "approve",
"sandbox": "danger-full-access",
"note": "用户确认该项目位于隔离的 codex_trae_workspace 中，可以重试。"
}拒绝示例：
{
"requestId": "permission-request-id",
"decision": "reject",
"note": "缩小任务范围后再提交。"
}danger-full-access 只建议在你已经用 codex_trae_workspace 或其他方式隔离执行环境时使用。
npm install
npm run build
npm run dev项目结构：
src/
cli.ts # MCP stdio 入口
executor.ts # Codex 命令执行器适配层
index.ts # 库导出
mcp-server.ts # MCP 工具定义与请求处理
task-manager.ts # 任务、日志、产物、权限请求管理
types.ts # 类型定义
skills/
trae-codex-workspace/
SKILL.md # 可安装到 TRAE 的 skill不要把 API Key、账号密码、中转站凭据写入任务 prompt。
projectRoot 必须位于 SANDBOX_ROOT 内。
默认使用 workspace-write。
谨慎批准 danger-full-access 重试。
TRAE 应负责最终验收，不要盲目接受 Codex 子任务结果。
MCP server 通过 stdio 通信，启动日志写入 stderr，避免污染 stdout。
任务状态持久化，避免 MCP 进程重启后丢失内存状态。
更精细的权限请求解析，展示被阻止的命令。
多 Codex profile / 多中转站配置。
端到端测试夹具。
英文 README。
MIT
Cancel a running or pending task
| Name | Required | Description | Default |
|---|---|---|---|
| taskId | Yes | Task ID to cancel |
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 indicates a mutative action ('cancel') but fails to disclose side effects, reversibility, permission requirements, or post-cancellation state, which is insufficient for a destructive operation.
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, concise sentence that front-loads the key information without any unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (1 param, no output schema, no annotations), the description lacks completeness by not covering return behavior, error cases, or constraints like ownership/permissions.
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?
With 100% schema coverage, the description adds no extra meaning beyond the schema's parameter description ('Task ID to cancel'). Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Cancel' and the resource 'task', specifying the applicable states 'running or pending'. This distinguishes it from sibling tools like submit_task, list_tasks, and get_task_status.
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 canceling tasks in a running or pending state, but lacks explicit guidance on when not to use it (e.g., if task is already completed) or alternatives like checking status first.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check the MCP environment configuration
| 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 must fully disclose behavior. It only says 'Check', implying a read-only operation, but does not mention side effects, output format, or any specific configuration categories checked.
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 with a single phrase, no wasted words. It is appropriately sized for a simple diagnostic tool with no parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and the tool's simplicity, the description still lacks completeness. It does not describe return values, typical use cases, or how the output can be interpreted. For a diagnostic tool, more context would be helpful.
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 no parameters, so schema coverage is 100%. The description adds no param-specific information, which is acceptable since there are none. Baseline 4 applies for zero 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 clearly states the verb 'Check' and the resource 'MCP environment configuration', which is distinct from sibling tools that focus on tasks, permissions, and artifacts. The purpose is immediately understandable.
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 is provided on when to use this tool versus alternatives, such as diagnostic contexts or prerequisites. The description lacks any explicit or implicit usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a compact dashboard with task counts, recent tasks, and pending permission requests
| Name | Required | Description | Default |
|---|---|---|---|
| projectRoot | No | Optional project root filter | |
| limit | No | Maximum number of recent task summaries to return |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility for behavioral disclosure. It only lists content components without explaining side effects, caching, permission requirements, or whether it is read-only. The lack of any behavioral detail is a significant gap.
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, front-loaded sentence that conveys the core purpose without extra words. Every part of the description contributes value, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lists three data components but lacks detail on the return format (e.g., how counts are aggregated, what constitutes 'recent'). Given the absence of an output schema, a more complete description would improve usability, but the high-level summary is minimally adequate.
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%—both parameters are described in the schema (projectRoot as optional filter, limit as max recent tasks). The description adds no additional meaning beyond the schema, so a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a 'compact dashboard' containing 'task counts, recent tasks, and pending permission requests'. The verb 'Get' is specific, and the resource is well-defined. It implicitly distinguishes from sibling tools like list_tasks and list_permission_requests by combining their data.
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 vs. alternatives like list_tasks or list_permission_requests. The description does not mention use cases, prerequisites, or exclusions, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the final result report for a completed task
| Name | Required | Description | Default |
|---|---|---|---|
| taskId | Yes | Task ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Only states 'gets' a report, implying a read operation, but omits details on side effects, idempotency, or behavior if task is not completed. Minimal disclosure.
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, no redundancy, every word adds value. Front-loaded with essential 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?
Adequate for a simple retrieval tool, but could benefit from clarifying report format or error conditions. Given no output schema and no annotations, completeness is minimal but sufficient for common use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage with description 'Task ID' for the only parameter. Baseline is 3 per rules; description does not add extra meaning beyond schema, but schema alone is clear enough.
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 the tool gets a final result report for a completed task. It specifies the resource ('result report') and condition ('completed task'), distinguishing it from siblings like get_task_status (status) or get_task_log (logs).
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?
Implies usage only for completed tasks, but does not explicitly state when to use vs. avoid, nor reference alternatives like get_task_log or list_artifacts. No guidance on prerequisites or fallback options.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get execution logs for a task
| Name | Required | Description | Default |
|---|---|---|---|
| taskId | Yes | Task ID | |
| maxChars | No | Maximum characters to return |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must cover behavior. It does not disclose read-only nature, authentication needs, rate limits, or what happens if the task is still running. Merely states the action without 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no clutter. Could benefit from an extra sentence explaining return format, but it is concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks information about return value format (e.g., plain text, JSON), pagination, or error handling. Without output schema or annotations, description should provide more context for effective use.
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 covers both parameters with descriptions (100% coverage). The tool description adds no additional parameter context beyond what schema already provides. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Get execution logs for a task', which is a specific verb and resource. It distinguishes from siblings like get_task_status. However, it could elaborate on what constitutes 'execution logs' (e.g., text output).
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 get_task_status or list_artifacts. Does not mention prerequisites or scenarios where logs are available.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the status of a task
| Name | Required | Description | Default |
|---|---|---|---|
| taskId | Yes | Task ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden for behavioral transparency. The minimal description 'Get the status of a task' does not disclose whether it is read-only, what permissions are needed, if it has side effects, or what the response format is. The behavioral traits are largely undisclosed.
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 with no wasted words. It is concise and front-loaded. However, it might be too terse given the lack of detail, but it earns a 4 for efficient use of language.
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 there is no output schema and no annotations, the description should provide more context such as possible status values or return format. It fails to do so, making it incomplete for a tool that returns status. The tool is simple but still lacking essential contextual details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters with a description for 'taskId' as 'Task ID'. The description adds no additional meaning beyond what the schema provides. Baseline 3 is appropriate because the schema already documents the parameter sufficiently.
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 'Get the status of a task' clearly states the verb and resource. It distinguishes from siblings like 'list_tasks' (which lists tasks) and 'cancel_task' (which cancels), but does not explicitly differentiate from 'get_task_log' which retrieves logs, not status. The purpose is clear but lacks explicit sibling differentiation.
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 is provided on when to use this tool versus alternatives. The description does not mention any prerequisites, context, or exclusions. There is no mention of when to use 'get_task_status' instead of related tools like 'get_task_log' or 'list_tasks'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List files and artifacts produced by a task
| Name | Required | Description | Default |
|---|---|---|---|
| taskId | Yes | Task ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose safety, authentication, or response behavior, but it only states the basic function without any behavioral details (e.g., read-only nature, pagination).
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, concise sentence with the verb and object front-loaded; no superfluous words, though it could be expanded slightly for clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one required parameter and no output schema, the description covers the core purpose but omits details about what constitutes an artifact, response format, or any constraints, leaving gaps for complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already describes the parameter; the description adds no extra meaning beyond 'Task ID', keeping the baseline score.
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 ('List') and the resource ('files and artifacts produced by a task'), which distinguishes it from sibling tools like list_tasks and get_task_log.
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 explicit guidance on when to use this tool versus alternatives; it only implies usage for retrieving artifacts for a given task, but does not mention exclusions or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List permission requests created after Codex fails due to sandbox or approval restrictions
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | Optional permission request status filter | |
| taskId | No | Optional task ID filter |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It does not disclose whether the operation is read-only, what the response looks like, or any behavioral traits beyond listing. 'List' implies safe reading, but this is not explicitly stated.
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 is front-loaded and efficient. It earns its place, though it could slightly expand on usage context without becoming verbose.
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?
Despite having no output schema and no annotations, the description is minimal. It does not cover return format, pagination, ordering, or filtering behavior beyond schema fields. For a list tool, more context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents both parameters with descriptions. The description adds no additional meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'List permission requests' and specifies the context 'created after Codex fails due to sandbox or approval restrictions'. This distinguishes it from siblings like list_tasks and resolve_permission_request.
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 a specific usage scenario (when Codex fails), but does not explicitly state when not to use the tool or provide alternatives. No guidance on exclusions or comparisons to other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List task summaries for TRAE desktop/mobile progress views
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | Optional task status filter | |
| projectRoot | No | Optional project root filter | |
| limit | No | Maximum number of tasks to return |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It does not disclose whether the operation is read-only, sorting behavior, pagination limits, data freshness, or authentication requirements. The term 'summaries' hints at reduced detail but lacks specificity.
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, front-loaded sentence that conveys the core purpose efficiently. Every word earns its place, though it could benefit from additional structure to improve scannability.
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 lack of output schema and the need to understand what fields 'task summaries' include, the description is incomplete. It does not clarify the return value structure, default limit, ordering, or how to interpret the summaries, leaving the agent uncertain.
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 all three parameters described in the input schema. The description adds no additional meaning beyond the schema, meeting the baseline. No parameter-specific information is provided in the description text.
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 (list), resource (task summaries), and context (TRAE desktop/mobile progress views). It effectively distinguishes from sibling tools like get_task_status (detailed status) and cancel_task (action).
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 progress views but provides no explicit guidance on when to use this tool versus alternatives like get_task_status or list_artifacts. No exclusions or conditions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Request revision for a task
| Name | Required | Description | Default |
|---|---|---|---|
| taskId | Yes | Original task ID | |
| revisionNotes | Yes | Notes explaining what needs to be revised | |
| model | No | Model to use | |
| sandbox | No | Sandbox access mode | |
| autoStart | No | Whether to auto-start |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It only states the tool's action without revealing side effects (e.g., does it modify existing tasks? create a new revision? require permissions?). Critical transparency is missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (one sentence) and front-loaded. While efficient, it sacrifices necessary detail for completeness; a bit more context could be added without losing 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?
Given the tool has 5 parameters and no output schema or annotations, the description is insufficient. It does not explain the revision process, what happens after request, or how the response is handled.
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%, so the baseline is 3. The tool description adds no additional parameter meaning beyond the schema's own descriptions, meeting the minimum expectation.
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 is a clear verb+noun ('Request revision for a task'), accurately stating the tool's intent. However, it does not differentiate from sibling tools like submit_task or cancel_task, missing an opportunity to clarify unique scope.
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 is provided on when to use this tool versus alternatives (e.g., submit_task for new tasks, cancel_task for termination). The description lacks any contextual cues for appropriate invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Approve or reject a pending permission request. Approval creates a retry task with the requested sandbox.
| Name | Required | Description | Default |
|---|---|---|---|
| requestId | Yes | Permission request ID | |
| decision | Yes | Whether to approve or reject the request | |
| note | No | Optional approval or rejection note | |
| sandbox | No | Sandbox to use for the retry task when approving | |
| autoStart | No | Whether the retry task should start immediately |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses that approval creates a retry task and requires a sandbox, but does not describe what happens on rejection, side effects, or permissions needed. Partially transparent but incomplete.
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, no fluff, front-loaded with the core action. 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?
For a mutation tool with 5 parameters and no output schema or annotations, the description is incomplete. It doesn't explain return values (e.g., response object), error conditions, or what happens to the original request. More detail is needed.
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% (5/5 parameters described). Description adds no additional meaning beyond schema; it merely mentions sandbox in context of retry task. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool's action: 'Approve or reject a pending permission request', and adds a key behavioral outcome: 'Approval creates a retry task with the requested sandbox.' This distinguishes it from sibling tools like list_permission_requests, which only list requests.
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 explicitly state when to use this tool versus alternatives like request_revision or submit_task. It implies that approval triggers a retry task, but no guidance on prerequisites (e.g., request must be pending) or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Submit a development task to the executor agent
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | Task description (required) | |
| title | No | Task title | |
| model | No | Model to use for execution | |
| sandbox | No | Sandbox access mode | |
| autoStart | No | Whether to auto-start the task | |
| constraints | No | Task constraints | |
| acceptanceCriteria | No | Acceptance criteria | |
| projectRoot | No | Project root directory |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description gives no behavioral details (e.g., whether submission is synchronous, returns a task ID, or has side effects).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words; it is appropriately concise given its limited scope.
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?
With 8 parameters, 1 required, nested objects, and no output schema, the description is far too minimal to inform correct usage; it omits crucial context like return values and execution behavior.
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 parameters are documented there. The description adds no additional meaning 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 action ('submit') and the resource ('development task'), and it distinguishes from sibling tools like cancel_task and list_tasks.
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; lacks context about prerequisites or scenarios.
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.
v1.0.0cancel_taskdiagnose_environmentget_mobile_dashboardget_result_reportget_task_logget_task_statuslist_artifactslist_permission_requestslist_tasksrequest_revisionresolve_permission_requestsubmit_taskScored across 12 tools
Each tool targets a distinct operation: task lifecycle (submit, cancel, status, logs, artifacts, report), permissions (list, resolve), environment diagnostics, dashboard, and revision. No two tools overlap in purpose.
All tool names follow the verb_noun snake_case pattern (e.g., cancel_task, list_permission_requests). The naming is uniform and predictable across the entire set.
With 12 tools, the set is well-scoped for an agent orchestration server. Each tool serves a clear function without redundancy, and the count is appropriate for the domain complexity.
The tool surface covers the main task lifecycle (submit, cancel, status, logs, artifacts, report), permissions, environment check, and revision. Minor missing features like direct task update or retry are handled indirectly, leaving only small gaps.
Cross-agent artifact workspace with provenance across Claude Code, Codex, Cursor, LangGraph.
Coordination hub for AI coding agents: message teammates, ask humans, audit every event.
Shared control plane for AI coding agents — tasks, memory, decisions, file locks. 12 tools.
AI work orchestration for plans, tasks, teams, and coding-agent dispatch.
