> ## Documentation Index
> Fetch the complete documentation index at: https://docs.myrmagent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools API

> 以编程方式管理与执行工具。

# Tools API

## 列出可用工具

```bash theme={null}
GET /api/tools
```

## 执行工具

```bash theme={null}
POST /api/tools/:name/execute
```

```json theme={null}
{
  "parameters": {
    "url": "https://example.com"
  }
}
```

## 内置工具

| 工具                  | 说明                                                                                                                         |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `browser`           | 网页浏览与抓取                                                                                                                    |
| `file_system`       | 文件读写                                                                                                                       |
| `terminal`          | Shell 命令执行                                                                                                                 |
| `code_execute`      | 沙箱内代码执行                                                                                                                    |
| `grep_tool`         | Ripgrep 正则内容搜索（三档：ripgrep → mmap → Python），路径分组密集化输出（≥5 匹配时自动去冗余路径，省 18-39% Token），ReDoS 防护，非代码文件自动截断                      |
| `glob_tool`         | 工作区内文件路径模式搜索                                                                                                               |
| `@codebase` mention | 轻量工作区文件/扩展名概览，注入用户消息（配合 grep/glob 探索代码）                                                                                    |
| `web_search`        | 多引擎搜索 + BM25/Reranker 过滤 — 返回清洗、去重片段                                                                                       |
| `render_ui`         | 对话内声明式 UI（23 种 A2UI 组件）。Turn1 \~223 tok；完整 props 见 `.agent/docs/A2UI_REFERENCE.md`（启用时自动 seed）。未知 type fail-closed         |
| `update_ui_data`    | 增量 `data_update` SSE，用于进度条/指标/任务列表等长生命周期面板。`data` 模型深合并——嵌套字段更新不 wipe 兄弟键。与 `render_ui` 同组挂载（开启交互式 UI 时可用）                 |
| `todo_write`        | 多步骤目标的结构化任务规划。硬性约束 MAX\_TODOS=20 防止过度规划；单一 `in_progress` 并发限制保持执行聚焦。违规自动纠正并反馈 LLM。通过 Planning 开关按需启用，或在续聊时检测到已有 todos 自动启用 |

### 默认工具组 vs 按需能力

| 场景          | 默认启用                                                                                                | 按需开启                                                                        |
| ----------- | --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| 普通对话        | `web_search` + `memory`                                                                             | —                                                                           |
| 编码 / 文件     | 勾选 **file\_ops** → `glob_tool` + `grep_tool` + file\_\* **立即挂载**（与 Claude Code 同款 eager，非 discover） | `code_execute`（bash）                                                        |
| MCP / 已绑定技能 | —                                                                                                   | `discover_capability_tool` → `skill_select_tool` 搜**已绑定**库（`<BoundSkills>`） |
| 外部技能市场      | —                                                                                                   | `skill_discovery_tool` 从 GitHub/skills.sh **安装新技能**；Settings「发现」Tab 亦可浏览    |
| Skill 质量清理  | WebUI **Curator** 一键 sweep                                                                          | —                                                                           |

\| `web_fetch` | 3 级本地抓取（HTTP/Browser/Stealth）+ DOM 剪枝与 Markdown 提取 |
\| `github` | GitHub API 集成 |

## MCP 工具

通过 [MCP](/zh/guides/mcp-integration) 连接的外部工具与内置工具一并注册。MCP 工具名内部前缀为 `mcp__{server}__{tool}` 以隔离命名空间 — API 接受前缀名与原始名。

```bash theme={null}
POST /api/tools/mcp__github__search_repos/execute
```

### 两路智能路由

连接工具数量多的 MCP 服务时，系统自动选择最优路由策略以最小化 token 消耗，同时保留完整的工具访问能力：

| 路由              | 条件                | 行为                                               | 用户体验       |
| --------------- | ----------------- | ------------------------------------------------ | ---------- |
| **Direct**      | 服务工具数 ≤ 阈值 且在总预算内 | 完整 schema 预加载                                    | 零延迟调用      |
| **PTC / Skill** | 服务工具数 > 阈值 或超出总预算 | 封装为 Skill（`skill_search` → `skill_select` → PTC） | 通过技能搜索按需发现 |

连接 50+ 工具的 MCP 服务不会撑大 Turn1 prompt — 大服务降级为 Skill 按需发现。Direct 工具在 UI 显示真实工具名。

<Callout type="info">
  安全规则（ALLOW/ASK/DENY）对 Direct 与 Skill/PTC 路径均生效。针对 `mcp__gmail__send_email` 的 DENY 规则无法通过 Skill 路径绕过。
</Callout>

### 过滤

可在 MCP 服务配置中用 `tool_include` / `tool_exclude` 按 Agent 过滤：

```json theme={null}
{
  "tool_include": ["search_repos", "get_issue"],
  "tool_exclude": ["delete_repo"]
}
```

详见 [MCP 集成 > 工具过滤](/zh/guides/mcp-integration#tool-filtering)。