# 工具 API 参考

本页汇总工具目录、工作区工具和专用外部服务连接接口。认证与工作区规则见 [Product API 开始使用](../../product-api/getting-started.md)。

## 工具接口

| 方法 | 相对路径 | 用途 |
| --- | --- | --- |
| `GET` | `/workspaces/{workspace_id}/tools` | 列出系统或工作区工具。 |
| `GET` | `/workspaces/{workspace_id}/tools/tags` | 列出工具标签及数量。 |
| `GET` | `/workspaces/{workspace_id}/tools/{tool_id}` | 读取工具详情。 |
| `POST` | `/workspaces/{workspace_id}/tools` | 创建工作区工具。 |
| `PATCH` | `/workspaces/{workspace_id}/tools/{tool_id}` | 部分更新或归档工作区工具。 |

列表支持 `query`、`status`、`kind`、`category`、`phase`、`side_effect_class`、运行时可见性、绑定类型、重复的 `tags`、`catalog`、`limit` 和 `offset`。

## 创建和更新字段

| 字段 | 类型 | 必需 | 默认值 | 说明 |
| --- | --- | --- | --- | --- |
| `name` | string | 创建时是 | — | 工具名称。 |
| `description` | string | 否 | — | 工具完成的单一动作。 |
| `status` | string | 否 | — | 工具状态。归档使用 `archived`。 |
| `kind` | string | 否 | — | 工具类型。 |
| `category`、`tags`、`phase` | string、array、string | 否 | — | 分类和检索信息。 |
| `source_ref` | object | 否 | — | 执行来源的类型、ID、URI、版本和配置。 |
| `input_schema` | object | 否 | — | 输入 JSON Schema。 |
| `output_schema` | object | 否 | — | 输出 JSON Schema。 |
| `side_effect_class` | string | 否 | — | 工具副作用类别。 |
| `credential_ref` | string | 否 | — | 已保存凭据的引用。 |
| `approval_policy_ref` | string | 否 | — | 批准策略引用。 |
| `redaction_policy_ref` | string | 否 | — | 脱敏策略引用。 |

详情响应还可能包含 `bindable`、`bindability_reason` 和 `supported_runtimes`。这些字段反映当前可绑定状态，不是工具定义的静态承诺。

## 专用连接接口

| 方法 | 相对路径 | 用途 |
| --- | --- | --- |
| `POST`、`GET`、`DELETE` | `/workspaces/{workspace_id}/tools/github/connect` | 连接、查询或断开 GitHub 工具。 |
| `POST` | `/workspaces/{workspace_id}/tools/wecom/callback-secrets/generate` | 生成企业微信回调密钥材料。 |
| `POST`、`GET`、`DELETE` | `/workspaces/{workspace_id}/tools/mail/{provider}/connect` | 连接、查询或断开邮件工具；`provider` 为 `qq` 或 `wecom`。 |
| `POST`、`GET`、`DELETE` | `/workspaces/{workspace_id}/tools/grafana/connect` | 连接、查询或断开 Grafana 工具。 |

创建连接时传入第三方凭据。查询连接时检查 `status`、`credential_ref` 和是否需要重新连接；不要依赖服务回显明文密钥。

## 错误和限制

| 现象 | 先检查 | 处理方式 |
| --- | --- | --- |
| 工具存在但不可绑定 | `bindable`、`bindability_reason`、目标运行时 | 补齐凭据或改用受支持运行时。 |
| 调用参数无效 | `input_schema` 与实际参数 | 修正 Schema 或调用参数，避免用提示词猜测字段。 |
| 第三方认证失败 | 连接状态、令牌范围和过期时间 | 使用最小必要权限重新连接。 |
| 更新冲突或资源不可修改 | 工具来源和所属工作区 | 不修改系统工具；对正确的工作区工具提交更新。 |

## 任务指南

- [发现和管理工具](manage-tools.md)
- [连接 MCP 服务并导入工具](../mcp-connections/connect-import-tools.md)