Tools Block

声明当前上下文中可用的工具集合，控制后续 Generation Block 能够调用哪些工具。

功能说明

Tools Block 是一个声明式节点（isDeclarative = true），它本身不执行具体操作，而是配置后续 AI 生成步骤可以使用的工具列表。工具可以来自 workflow、Skill 或 MCP。区别在于 Flow Block 运行到时会立即执行，而 Tools Block 只是声明工具供后续 AI 按需调用。

执行到 Tools Block 时，它会把声明的工具加入当前声明作用域，并设置工具调用策略（auto 或 required）。同级多个 Tools Block 会累加合并；进入/离开分支、循环等容器时，声明作用域会随执行路径自动生效或失效。

当你需要让 AI 在生成过程中调用外部工具（如调用其他 workflow、skill 或 MCP 服务）时，在 Generation Block 之前放置 Tools Block 来声明可用工具。

使用场景

• AI Agent 工具配置：为 AI 提供一组可调用的 workflow 或 skill 工具，让 AI 根据上下文自动选择使用
• MCP 集成：声明外部 MCP 服务提供的工具，让 AI 能够调用第三方 API
• 工具约束：通过 toolChoice 参数控制 AI 是否必须使用工具（required）或自行判断（auto）

配置参数

属性名	类型	说明	默认值
tools	string	工具列表（JSON 序列化的 ToolItem[]）	'[]'
toolChoice	'auto' | 'required'	工具调用策略：auto=AI 自行决定, required=必须调用工具	'auto'

ToolItem 结构

每个工具项包含以下字段：

字段	类型	说明
type	'workflow' | 'skill' | 'mcp'	工具来源类型
id	string	工具的唯一标识
label	string	工具显示名称
server	string	MCP 类型时的服务器标识（可选）

toolChoice 说明

值	行为
auto	AI 根据上下文自行决定是否调用工具
required	AI 必须至少调用一个工具

输出变量

无。Tools Block 是声明式节点，不产生可被 @{} 引用的输出变量。真正的工具调用结果会进入后续 AI Block 的工具调用上下文，并体现在该 AI Block 的输出、tool events 和 Run 历史中。

使用示例

示例 1：AI Agent 调用 workflow 工具

配置一组 workflow 工具，让 AI 根据用户请求自动选择调用：

[Tools Block: agent_tools] — toolChoice: auto
    工具列表:
    - type: workflow, label: "search_docs", id: "doc-xxx"
    - type: workflow, label: "send_email", id: "doc-yyy"
    |
[Generation Block] — "根据用户的请求选择合适的工具执行: {{input}}"
    （AI 会根据 prompt 内容决定是否调用 search_docs 或 send_email）

示例 2：强制使用 MCP 工具

配置 MCP 服务工具，并要求 AI 必须调用：

[Tools Block] — toolChoice: required
    工具列表:
    - type: mcp, label: "web_search", server: "search-server"
    |
[Generation Block] — "搜索关于量子计算的最新论文"
    （AI 必须调用 web_search 工具）

运行时约束

• 适用文档类型：workflow（Slash 菜单中排除了 skill 类型文档）
• 可插入上下文：顶层文档、Condition 分支、Loop 内、Promise 分支
• 不可嵌套场景：无特殊限制

AllowTools（Skill 文档专用）

在 Skill 类型文档中，使用 AllowTools 替代 Tools Block 来声明可用工具。AllowTools 的功能与 Tools Block 等同，但专为 Skill 文档设计——Skill 文档不使用 inputsOrTrigger（输入/触发器），而是通过 AllowTools 声明 AI 可调用的工具集。

如果 Tools 中声明的是 Skill，后续 AI Block 会先看到 Skill 的标题和描述；只有当 AI 判断需要时，才会调用 loadSkill 展开完整说明。完整机制见 Skill 运行机制。

注意事项

1. 声明作用域：同级多个 Tools Block 会累加合并；容器内声明只在对应分支或循环内部生效；空工具列表会在当前作用域禁用工具调用。
2. 空工具列表：如果配置的工具列表为空，会清除所有活跃工具并将 toolChoice 设为 none
3. 工具解析：运行时会自动解析工具定义，将 workflow/skill 的 ID 转换为实际可调用的工具。部署或运行时如果目标文档不存在、跨项目或类型不匹配，会显式失败，避免静默绑定错误工具。
4. 声明式节点：Tools Block 本身不消耗积分，不产生内容输出。它只是配置工具环境，真正的工具调用发生在后续的 Generation Block 中
5. 兼容旧格式：Tools Block 向后兼容旧版 allowTools Block 的数据格式