building-tools

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Building Tools

构建工具

A tool is Celigo's first-class reusable building block. It encapsulates logic -- lookups, imports, transforms, branching -- behind a defined input and output contract. Build it once, use it everywhere: from Flows, APIs, AI Agents, MCP Servers, and other Tools.

工具是Celigo的一等可复用构建块。它将查询、导入、转换、分支等逻辑封装在定义好的输入输出契约之后。一次构建，随处使用：可在Flows、APIs、AI Agents、MCP Servers及其他工具中调用。

Tool Concepts

工具核心概念

Why tools exist: Without tools, users build the same lookup-transform-import patterns repeatedly across Flows, APIs, and Agents. Tools solve this by providing a governed, composable abstraction: one definition, many consumers, consistent behavior.

When to build a tool:

You're building an MCP server -- MCP servers expose tools as endpoints; every piece of logic an MCP server offers must be a tool
The same logic is needed by 2+ consumers (flows, APIs, agents, MCP servers) -- build once, call everywhere
You want connection flexibility -- callers can pass different connections to the same tool definition
You're composing smaller pieces -- tools can call other tools for nested orchestration

When NOT to build a tool:

The logic is specific to one flow or API and won't be reused -- inline it as a lookup/import processor directly
You need abstract/instance templating for multi-tenant patterns -- use abstract flows

Tool vs API: the split is how the work gets invoked. An API is reachable from outside Celigo over HTTP (a partner system, a customer-facing app). A tool is reachable only from inside Celigo (flow steps, AI agents, APIs, other tools). If a recipe must be reachable from both, build it as a tool and expose the tool behind an API endpoint -- the tool stays available to inside-Celigo consumers at the same time.

Tool vs flow: tools don't start themselves -- no

schedule

, no listeners, no flow runtime controls (

proceedOnFailure

and friends are the consumer's concern), and no abstract/instance layer (a tool is already the unit of reuse; per-environment variation is handled by the consumer-bound connection model). "Every night, do X" or "when a webhook arrives, do Y" is a flow -- the tool may be the thing the flow does.

Architecture:

Tool
+-- input         -- JSON Schema defining what callers send
+-- routers[]     -- processing pipeline
|   +-- branches[]
|       +-- pageProcessors[]  -- lookups (exports), imports, transfers
+-- output        -- schema, mappings, lookups, hooks defining what the tool returns

Routers hold branches, branches hold page processors. Use multiple branches when different inputs need different processing paths. Chain routers via

nextRouterId

for sequential processing stages. The special

nextRouterId: "outputRouter"

exits the tool and returns results.

工具存在的意义： 没有工具时，用户会在Flows、APIs和Agents中重复构建相同的查询-转换-导入模式。工具通过提供可管控、可组合的抽象层解决这一问题：一份定义，多类消费者，行为一致。

何时构建工具：

你正在构建MCP Server——MCP Server将工具作为端点暴露；MCP Server提供的每一段逻辑都必须是工具
同一逻辑需要被2个及以上消费者（流程、API、Agent、MCP Server）使用——一次构建，随处调用
你需要连接灵活性——调用者可为同一工具定义传入不同的连接
你正在组合更小的组件——工具可以调用其他工具实现嵌套编排

何时无需构建工具：

逻辑仅针对单个流程或API，无需复用——直接作为查询/导入处理器内联使用
你需要针对多租户模式的抽象/实例模板——使用抽象流程

工具 vs API： 区别在于工作的调用方式。API可通过HTTP从Celigo外部访问（如合作系统、客户应用）。工具仅能从Celigo内部访问（流程步骤、AI Agents、APIs、其他工具）。如果某个逻辑需要同时被内外访问，可先构建为工具，再通过API端点暴露——工具仍可被Celigo内部消费者调用。

工具 vs 流程： 工具不会自行启动——没有

schedule

、监听器或流程运行时控制（

proceedOnFailure

等属于消费者的关注点），也没有抽象/实例层（工具本身就是复用单元；环境差异由消费者绑定的连接模型处理）。"每晚执行X操作"或"收到Webhook时执行Y操作"属于流程——工具可能是流程执行的具体内容。

架构：

Tool
+-- input         -- JSON Schema定义调用者传入的数据
+-- routers[]     -- 处理流水线
|   +-- branches[]
|       +-- pageProcessors[]  -- 查询（导出）、导入、传输
+-- output        -- 定义工具返回结果的 schema、映射、查询、钩子

Routers包含branches，branches包含page processors。当不同输入需要不同处理路径时，使用多分支。通过

nextRouterId

链式连接routers实现顺序处理阶段。特殊值

nextRouterId: "outputRouter"

会退出工具并返回结果。

Tool Execution Pipeline

工具执行流水线

When a tool is invoked:

Input received -- input data validated against the tool's JSON Schema (
```
input
```
)
Router evaluation --
```
routeRecordsUsing
```
evaluates branch conditions (if multiple branches exist)
Branch selection -- matching branch processes the input
Page processors -- each processor executes sequentially (export lookups, import writes)
Response mapping --
```
responseMapping
```
on each processor carries data to the next processor
Output mapping -- final output mapped according to the tool's
```
output
```
configuration (schema, mappings, lookups, hooks)
Return -- output returned to the caller (flow, API, AI agent, MCP server)

Execution mode depends on the caller:

Called from a Flow -- runs in flow mode (batch-oriented, run console, error management)
Called from an API -- runs in API mode (single request/response)
Called from an AI Agent -- runs with agent context; agent maps connections to the tool
Called from an MCP Server -- exposed as an MCP tool endpoint for external AI clients
Called from another Tool -- nested execution within the parent tool's context

Connection model: Always bring-your-own-keys. The caller (flow, API, agent, MCP server) maps connections to the tool at configuration time. MCP Server overrides can swap connections per-server without modifying the tool.

Build order: Connection --> Export + Import --> Tool --> (consumer: Flow / API / Agent / MCP Server)

Concerns beyond the build steps:

Response mapping -- extract fields from processor responses back into the record. Configured on
```
pageProcessors[]
```
entries within branches, but planned when building the processors. For lookups the response has
```
data[]
```
and
```
errors[]
```
(use
```
data[0].fieldName
```
for single results); for imports use
```
_json.fieldName
```
. Uses Transformation 1.0 syntax (extract/generate pairs)
postResponseMap hook -- JavaScript processing after response mapping. Also on
```
pageProcessors[]
```
entries, but planned when building the processors

工具被调用时：

接收输入——输入数据会根据工具的JSON Schema（
```
input
```
）进行验证
路由评估——
```
routeRecordsUsing
```
评估分支条件（如果存在多个分支）
选择分支——匹配的分支处理输入数据
执行页面处理器——每个处理器按顺序执行（导出查询、导入写入）
响应映射——每个处理器的
```
responseMapping
```
将数据传递给下一个处理器
输出映射——根据工具的
```
output
```
配置（schema、映射、查询、钩子）生成最终输出
返回结果——将输出返回给调用者（流程、API、AI Agent、MCP Server）

执行模式取决于调用者：

从Flow调用——以流程模式运行（面向批处理、运行控制台、错误管理）
从API调用——以API模式运行（单请求/响应）
从AI Agent调用——携带Agent上下文；Agent为工具映射连接
从MCP Server调用——作为MCP工具端点暴露给外部AI客户端
从其他Tool调用——在父工具的上下文中嵌套执行

连接模型： 始终采用"自带密钥"模式。调用者（流程、API、Agent、MCP Server）在配置阶段将连接映射到工具。MCP Server可通过覆盖配置，在不修改工具的情况下为每个服务器切换连接。

构建顺序： 连接 --> 导出 + 导入 --> 工具 -->（消费者：Flow / API / Agent / MCP Server）

构建步骤之外的关注点：

响应映射——从处理器响应中提取字段到记录中。配置在分支内的
```
pageProcessors[]
```
条目上，但需在构建处理器时规划。对于查询，响应包含
```
data[]
```
和
```
errors[]
```
（单结果使用
```
data[0].fieldName
```
）；对于导入，使用
```
_json.fieldName
```
。采用Transformation 1.0语法（提取/生成对）
postResponseMap钩子——响应映射后的JavaScript处理。同样配置在
```
pageProcessors[]
```
条目上，需在构建处理器时规划

The Two Flavors of Lookup

两种查询类型

"Lookup" refers to two different things in a tool. They live in different places and solve different problems:

Branch page-processor lookups (
```
pageProcessors[].type: "export"
```
) -- work-doing lookups inside a router branch that call an external system at runtime ("look up the customer in NetSuite by email"). The data isn't in the tool yet; the export fetches it, and a
```
responseMapping
```
pulls fields from the response onto the record so downstream branches and the output can see them. This is the same lookup primitive flows use -- same export resource, same response mapping, same
```
postResponseMap
```
hook.
Output static lookup tables (
```
output.lookups[]
```
) -- declarative value-translation tables on the output stage. They reach no external system; they are fixed key/value maps defined inline (e.g. a map translating
```
A
```
to
```
Active
```
,
```
I
```
to
```
Inactive
```
,
```
P
```
to
```
Pending
```
, with a
```
default
```
). An output
```
mappings[]
```
entry references a table by its
```
name
```
(via
```
lookupName
```
) to translate a field value during output assembly.

Rule of thumb: external system, runtime call --> branch page-processor lookup. Translate one value into another via a fixed table --> output static lookup.

在工具中，"Lookup"指两种不同的内容，它们位于不同位置，解决不同问题：

分支页面处理器查询（
```
pageProcessors[].type: "export"
```
）——路由分支内的功能性查询，在运行时调用外部系统（"通过邮箱在NetSuite中查询客户"）。数据尚未在工具中；导出操作获取数据，
```
responseMapping
```
将字段从响应提取到记录中，以便下游分支和输出使用。这与流程中使用的查询原语相同——相同的导出资源、响应映射和
```
postResponseMap
```
钩子。
输出静态查询表（
```
output.lookups[]
```
）——输出阶段的声明式值转换表。不访问任何外部系统；是内联定义的固定键值映射（例如将
```
A
```
映射为
```
Active
```
、
```
I
```
映射为
```
Inactive
```
、
```
P
```
映射为
```
Pending
```
，并设置
```
default
```
值）。输出的
```
mappings[]
```
条目通过
```
lookupName
```
引用表的
```
name
```
，在输出组装时转换字段值。

经验法则：访问外部系统、运行时调用 --> 使用分支页面处理器查询。通过固定表将一个值转换为另一个值 --> 使用输出静态查询表。

Consumer-Bound Connections

消费者绑定的连接

A tool never pins connections at design time -- the key difference from flows and APIs:

A flow or API pins each of its own steps to a specific connection at build time -- the connection IDs are baked into the resource.
A tool's lookups and imports declare the connections they need, and the consumer supplies the actual connection at bind time -- when the tool is added as a flow step, attached to an AI agent, exposed behind an API endpoint, or embedded in another tool.

The tool definition stays unchanged across every binding. The same tool can be bound with a sandbox NetSuite connection from one consumer and a production NetSuite connection from another, without forking. Mechanically, the tool's page processors reference underlying export and import resources that carry the connection; binding selects which connection records those resources use in that context. Because of this, knowing which connections a tool requires is part of its design -- those connections must already exist in the consumer's account before the tool can be bound and run there.

工具在设计阶段永远不会固定连接——这是与流程和API的关键区别：

流程或API在构建阶段会将每个步骤固定到特定连接——连接ID会被嵌入到资源中。
工具的查询和导入会声明所需的连接，消费者在绑定阶段提供实际连接——当工具被添加为流程步骤、附加到AI Agent、通过API端点暴露或嵌入到其他工具时。

工具定义在每次绑定中保持不变。同一工具可被一个消费者绑定到沙箱NetSuite连接，被另一个消费者绑定到生产NetSuite连接，无需分叉。从机制上讲，工具的页面处理器引用底层的导出和导入资源，这些资源携带连接；绑定操作选择这些资源在该上下文中使用的连接记录。因此，了解工具所需的连接是设计的一部分——在消费者账户中绑定和运行工具之前，这些连接必须已存在。

Quick Reference

快速参考

Decision Matrix

决策矩阵

You need to...	Build a tool?	Instead use
Reuse logic across 2+ flows/APIs/agents	Yes	--
Expose logic via MCP server	Yes	--
Allow callers to swap connections	Yes	--
Nest orchestration (tool calls tool)	Yes	--
One-off logic for a single flow	No	Inline lookup/import in flow
Multi-tenant templating	No	Abstract/instance flows

你需要...	是否构建工具？	替代方案
在2个及以上流程/API/Agent中复用逻辑	是	--
通过MCP Server暴露逻辑	是	--
允许调用者切换连接	是	--
嵌套编排（工具调用工具）	是	--
仅针对单个流程的一次性逻辑	否	在流程中内联查询/导入
多租户模板	否	抽象/实例流程

Minimum Required Fields

必填字段

Every tool needs at minimum:

name

_integrationId

, and an

input.schema

每个工具至少需要：

name

、

_integrationId

和

input.schema

。

Which Schemas to Read

需参考的Schema

Always: request.yml (base fields for create/update)
Input config: input.yml (schema, transform, mockInput)
Output config: output.yml (mappings, lookups, hooks)
Pipeline config: router.yml (routing strategy, branches, page processors, response mapping)
Response shape: response.yml

必看：request.yml（创建/更新的基础字段）
输入配置：input.yml（schema、转换、mockInput）
输出配置：output.yml（映射、查询、钩子）
流水线配置：router.yml（路由策略、分支、页面处理器、响应映射）
响应结构：response.yml

Schema Index

Schema索引

All schemas are in references/schemas/:

Base fields (create/update): request.yml
Response shape: response.yml
Input configuration: input.yml -- schema, transform, mockInput
Output configuration: output.yml -- mappings, lookups, hooks
Router and branch configuration: router.yml -- routing strategy, branches, page processors, response mapping

所有Schema都在references/schemas/中：

基础字段（创建/更新）： request.yml
响应结构： response.yml
输入配置： input.yml——schema、转换、mockInput
输出配置： output.yml——映射、查询、钩子
路由和分支配置： router.yml——路由策略、分支、页面处理器、响应映射

Related Skills

How to Build a Tool

如何构建工具

1. Determine the tool's purpose

1. 确定工具用途

What should this tool do when called? Define the inputs it expects and the processing steps it needs.

调用该工具时应实现什么功能？定义它期望的输入和所需的处理步骤。

2. Identify the integration

2. 确定所属集成

Every tool belongs to an integration. Find or create the integration first.

bash

celigo integrations list

每个工具都属于一个集成。先查找或创建集成。

bash

celigo integrations list

3. Check for existing patterns

3. 检查现有模式

Before building from scratch, look at what already exists:

bash

undefined

从零开始构建前，先查看已有的资源：

bash

undefined

Search your account (fast, uses local index)

搜索你的账户（快速，使用本地索引）

celigo account search "<keyword>"

Show what an existing tool uses (exports, imports, connections)

查看现有工具使用的资源（导出、导入、连接）

celigo account dependencies tool <id>

Find orphaned resources that could be reused

查找可复用的孤立资源

celigo account lint

Check if similar tools already exist

检查是否已有类似工具

celigo tools list

Search marketplace for pre-built integration templates

在市场中搜索预构建的集成模板

celigo templates marketplace


The account index auto-refreshes when stale (>4 hours). Force a fresh snapshot with `celigo account snapshot`.

Existing tools in the account are the best reference -- they show proven patterns for that specific customer's setup. Marketplace templates may provide a complete pre-built integration you can install rather than building from scratch.

celigo templates marketplace


账户索引会在过期时自动刷新（>4小时）。使用`celigo account snapshot`强制生成新快照。

账户中的现有工具是最佳参考——它们展示了针对特定客户环境的成熟模式。市场模板可能提供完整的预构建集成，你可以直接安装而非从零开始构建。

4. Build the connections, exports, and imports

4. 构建连接、导出和导入

Tools reference exports and imports as page processors in router branches. Build bottom-up: connections first, then exports and imports that use those connections, then the tool that wires them together. See

configuring-exports

and

configuring-imports

工具在路由分支中引用导出和导入作为页面处理器。自底向上构建：先创建连接，再创建使用这些连接的导出和导入，最后创建将它们连接在一起的工具。参考

configuring-exports

和

configuring-imports

。

5. Define the input schema

5. 定义输入Schema

The input schema is a JSON Schema object describing what data the tool accepts. For MCP compatibility, the root schema must have

type: "object"

输入Schema是一个JSON Schema对象，描述工具接受的数据。为了兼容MCP，根Schema必须有

type: "object"

。

6. Configure routing (if needed)

6. 配置路由（如有需要）

No routing -- all inputs processed the same way; skip routers entirely
Filter-based routing (
```
routeRecordsUsing: "input_filters"
```
) -- declarative expression rules on each branch
Script-based routing (
```
routeRecordsUsing: "script"
```
) -- custom JavaScript function returns the branch name

无需路由——所有输入都按相同方式处理；完全跳过routers
基于过滤器的路由（
```
routeRecordsUsing: "input_filters"
```
）——每个分支使用声明式表达式规则
基于脚本的路由（
```
routeRecordsUsing: "script"
```
）——自定义JavaScript函数返回分支名称

7. Wire page processors into branches

7. 将页面处理器接入分支

Each branch contains

pageProcessors[]

-- an ordered list of exports (lookups) and imports (actions). Each processor has:

```
type
```
:
```
"export"
```
or
```
"import"
```
```
_exportId
```
or
```
_importId
```
: reference to the resource
```
responseMapping
```
: extract fields from the processor response back into the record
```
hooks.postResponseMap
```
: optional script for post-processing
```
proceedOnFailure
```
: whether to continue if this step fails

每个分支包含

pageProcessors[]

——一个有序的导出（查询）和导入（操作）列表。每个处理器包含：

```
type
```
:
```
"export"
```
或
```
"import"
```
```
_exportId
```
或
```
_importId
```
: 引用资源ID
```
responseMapping
```
: 从处理器响应中提取字段到记录中
```
hooks.postResponseMap
```
: 可选的后处理脚本
```
proceedOnFailure
```
: 此步骤失败时是否继续执行

8. Configure output

8. 配置输出

Output mappings transform the processed data into the tool's return value. Supports:

```
mappings[]
```
-- extract/generate field pairs (Celigo standard mapping format)
```
lookups[]
```
-- static key-value enrichment tables
```
hooks.preMap
```
/
```
hooks.postMap
```
-- script hooks before and after mapping

Output mappings and branch response mappings both shape data, but at different times. Branch

responseMapping

merges a processor's response onto the in-flight record so downstream branches and routers can use it. Output

mappings

assemble the tool's return value at the very end -- and they only see the final in-flight record, not raw processor responses. If a processor's response field must appear in the output, it needs a response mapping on that processor first.

输出映射将处理后的数据转换为工具的返回值。支持：

```
mappings[]
```
——提取/生成字段对（Celigo标准映射格式）
```
lookups[]
```
——静态键值增强表
```
hooks.preMap
```
/
```
hooks.postMap
```
——映射前后的脚本钩子

输出映射和分支响应映射都用于塑造数据，但时机不同。分支的

responseMapping

将处理器的响应合并到流转中的记录，以便下游分支和路由使用。输出的

mappings

在最后组装工具的返回值——它们只能看到最终的流转记录，而非原始处理器响应。如果处理器的响应字段需要出现在输出中，必须先在该处理器上配置响应映射。

9. Build the JSON

9. 构建JSON

Reference the Schema Index for the exact fields needed. Use the Which Schemas to Read decision rule to determine which files to consult.

参考Schema索引获取所需的具体字段。使用需参考的Schema的决策规则确定要查看哪些文件。

Refactoring Steps into a Tool

将步骤重构为工具

A user can ask to factor a contiguous chunk of steps out of an existing flow, API, or tool into a brand-new reusable tool. The parent keeps behaving as before, but the selected steps are replaced by a single tool-step -- a thin wrapper that maps the parent's data into the new tool's input and binds the connections it needs. When the parent is itself a tool, the new resource is a sub-tool and the operation is tool composition -- same mechanics.

This operation is user-driven only. Trigger phrases: "refactor", "factor out", "extract", "turn this into a tool", "make this part reusable", "pull these steps out as their own tool". It is never something to propose unprompted -- reuse decisions belong to the user, and the operation creates real Celigo records and can mutate shared resources.

How it works:

The named steps are resolved to a contiguous selection with a single entry and a single exit (a valid tool topology).
The new tool's
```
input
```
and
```
output
```
schemas are designed against the real record shapes flowing through that boundary.
The wrapper is built for the parent to point at, then the parent is rewritten to remove the selected steps and splice in the new tool-step.

Entry and exit nodes never move. A flow's trigger steps, an API's request/response bookends, and a tool's input/output nodes are stripped from the selection regardless of whether the user included them -- only the body between them becomes the new tool.

No resources are cloned. The new tool's page processors reference the SAME export/import IDs the parent used inline. If those underlying exports/imports are then updated to fit the new tool's input/output shape, the change propagates to every other consumer of those resources (other flows, APIs, tools, MCP servers) -- a platform-wide invariant, not a refactor-specific effect.

Refactoring cannot be undone. There is no programmatic inverse; inlining a tool back into its parent is not supported. If the user regrets a refactor, cleanup is manual: delete the new tool and its wrapper, then restore the parent to its previous configuration. Refactor one parent at a time -- factoring steps from several parents into one shared tool is not a single operation.

用户可以请求将现有流程、API或工具中的连续步骤提取出来，构建为全新的可复用工具。父资源的行为保持不变，但选定的步骤会被单个工具步骤替换——一个轻量包装器，将父资源的数据映射到新工具的输入，并绑定所需的连接。当父资源本身是工具时，新资源是子工具，此操作是工具组合——机制相同。

此操作仅由用户驱动。触发词："重构"、"提取"、"转为工具"、"使其可复用"、"将这些步骤单独作为工具"。切勿主动提议——复用决策属于用户，此操作会创建真实的Celigo记录并可能修改共享资源。

工作原理：

将指定步骤解析为具有单个入口和单个出口的连续选择（有效的工具拓扑）。
根据流经该边界的实际记录形状设计新工具的
```
input
```
和
```
output
```
Schema。
为父资源构建指向新工具的包装器，然后重写父资源，移除选定步骤并插入新工具步骤。

入口和出口节点永远不会移动。无论用户是否选中，流程的触发步骤、API的请求/响应首尾、工具的输入/输出节点都会从选择中剥离——只有它们之间的主体部分会成为新工具。

不会克隆资源。新工具的页面处理器引用父资源内联使用的相同导出/导入ID。如果这些底层导出/导入随后被更新以适配新工具的输入/输出形状，更改会传播到这些资源的所有其他消费者（其他流程、API、工具、MCP Server）——这是平台级的不变性，而非重构特有的影响。

重构无法撤销。没有程序化的逆向操作；不支持将工具重新内联到父资源中。如果用户后悔重构，需要手动清理：删除新工具及其包装器，然后将父资源恢复到之前的配置。一次仅重构一个父资源——将多个父资源的步骤提取到一个共享工具中不是单一操作。

CLI Commands

CLI命令

bash

undefined

bash

undefined

CRUD

CRUD操作

celigo tools list celigo tools get <id> celigo tools create < tool.json celigo tools update <id> < tool.json celigo tools set <id> key=value [key2=value2 ...] celigo tools delete <id>

Manage page processors

管理页面处理器

celigo tools add-processor <id> <exportOrImportId> [--router <routerId>] [--branch <branchName>] [-y] celigo tools remove-processor <id> <exportOrImportId> [--router <routerId>] [--branch <branchName>] [-y]

Test run

测试运行

celigo tools test-run <id> celigo tools test-run-step-results <id> <runId> <exportOrImportId> celigo tools test-run-step-logs <id> <runId> <exportOrImportId>

Debug (requires debug enabled on the underlying export/import)

调试（需要底层导出/导入启用调试）

celigo tools debug-requests <id> <exportOrImportId> [--since <minutes>] celigo tools debug-request-detail <id> <exportOrImportId> <key>

Discovery

发现资源

celigo account search "<keyword>" celigo templates marketplace


<!-- TIER:3 -->

celigo account search "<keyword>" celigo templates marketplace


<!-- TIER:3 -->

Pre-Submit Checklist

提交前检查清单

Required (all tools)

必填项（所有工具）

```
name
```
is set
```
_integrationId
```
references a valid integration
```
input.schema
```
is defined with
```
type: "object"
```
at root (required for MCP compatibility)

已设置
```
name
```
```
_integrationId
```
引用有效的集成
```
input.schema
```
已定义，且根节点为
```
type: "object"
```
（兼容MCP的要求）

Pipeline

流水线

All
```
_exportId
```
/
```
_importId
```
references in page processors point to existing resources
Connections for referenced exports/imports are online
Router IDs are unique within the tool
All branches merge back to output node (no dangling branches)
Last branch in chain uses
```
nextRouterId: "outputRouter"
```
to exit the tool

页面处理器中所有
```
_exportId
```
/
```
_importId
```
引用都指向现有资源
引用的导出/导入对应的连接处于在线状态
工具内的Router ID唯一
所有分支都合并到输出节点（无悬空分支）
链中的最后一个分支使用
```
nextRouterId: "outputRouter"
```
退出工具

Cross-resource consistency

跨资源一致性

If response mapping needed: configured on
```
pageProcessors[]
```
entries within branches
If routing used:
```
routeRecordsUsing
```
and branch filters/scripts are configured correctly
If tool is for MCP: tool
```
name
```
is unique across all tool and API entries in the MCP server

如果需要响应映射：已在分支内的
```
pageProcessors[]
```
条目上配置
如果使用路由：已正确配置
```
routeRecordsUsing
```
和分支过滤器/脚本
如果工具用于MCP：工具
```
name
```
在MCP Server的所有工具和API条目中唯一

Gotchas

注意事项

PUT erases omitted fields. Always GET first, modify, then PUT. The
```
set
```
command handles this.
Router IDs must be unique within the tool. Branch
```
nextRouterId
```
must reference a real router
```
id
```
or the special
```
"outputRouter"
```
terminal value.
No dangling branches. All branches must merge back to the output node. A dangling branch causes a configuration error at execution time, even if no record takes that path.
Do not include
routeRecordsTo
or
routeRecordsUsing
on routers unless needed. If either is present, the API may also require a top-level
```
dataType
```
field, triggering validation errors. Omit both for simple tools -- the API defaults correctly.
Tools cannot be deleted while in use. Check "Used by" dependencies first (flows, APIs, agents, MCP servers referencing the tool).
add-processor
auto-creates a router. If the tool has no routers, the command creates a default router with one branch. Otherwise it targets the first router's first branch by default -- use
```
--router
```
and
```
--branch
```
to target a specific location.
Tool names must be unique in the MCP Server. The
```
name
```
field in
```
tools[]
```
on the MCP Server must be unique across all tool AND api entries in that server.
Debug logging is on the export/import, not the tool. Use
```
celigo exports enable-debug
```
or
```
celigo imports enable-debug
```
on the resources referenced by page processors, then use
```
celigo tools debug-requests
```
to view the logs scoped to the tool.
Test run results may be base64-encoded. The CLI auto-decodes these, but raw API responses need manual decoding.
Two different things are called "lookup." A branch page-processor lookup (
```
pageProcessors[].type: "export"
```
) calls an external system at runtime; an output static lookup table (
```
output.lookups[]
```
) is a fixed value-translation map that reaches nothing. They live in different parts of the tool and are not interchangeable.
Refactoring steps into a tool cannot be undone. There is no programmatic inline-back; cleanup is manual (delete the new tool and its wrapper, then restore the parent). The operation is user-driven only -- never initiate it unprompted, and it can update shared exports/imports that other consumers also use.

PUT操作会删除未指定的字段。始终先GET，修改后再PUT。
```
set
```
命令会处理此问题。
工具内的Router ID必须唯一。分支的
```
nextRouterId
```
必须引用真实的router
```
id
```
或特殊值
```
"outputRouter"
```
。
无悬空分支。所有分支必须合并到输出节点。即使没有记录走该路径，悬空分支也会在执行时导致配置错误。
无需时不要在routers上包含
routeRecordsTo
或
routeRecordsUsing
。如果存在其中任一字段，API可能还需要顶级
```
dataType
```
字段，从而触发验证错误。简单工具可省略这两个字段——API会自动设置默认值。
工具被使用时无法删除。先检查"被使用方"依赖（引用该工具的流程、API、Agent、MCP Server）。
add-processor
会自动创建router。如果工具没有routers，该命令会创建一个带单个分支的默认router。否则默认目标是第一个router的第一个分支——使用
```
--router
```
和
```
--branch
```
指定目标位置。
MCP Server中的工具名称必须唯一。MCP Server的
```
tools[]
```
中的
```
name
```
字段必须在该服务器的所有工具和API条目中唯一。
调试日志在导出/导入上，而非工具上。对页面处理器引用的资源使用
```
celigo exports enable-debug
```
或
```
celigo imports enable-debug
```
，然后使用
```
celigo tools debug-requests
```
查看工具范围内的日志。
测试运行结果可能是base64编码的。CLI会自动解码，但原始API响应需要手动解码。
有两种不同的"lookup"。分支页面处理器查询（
```
pageProcessors[].type: "export"
```
）在运行时调用外部系统；输出静态查询表（
```
output.lookups[]
```
）是固定的值转换映射，不访问任何外部系统。它们位于工具的不同部分，不可互换。
将步骤重构为工具无法撤销。没有程序化的内联操作；需要手动清理（删除新工具及其包装器，然后恢复父资源）。此操作仅由用户驱动——切勿主动发起，且可能更新其他消费者也在使用的共享导出/导入。

Common Errors

常见错误

Error	Cause	Fix
422 `_integrationId required`	Missing integration	Set `_integrationId` to a valid integration ID
422 `input.schema invalid`	Bad JSON Schema	Ensure root schema has `type: "object"` and valid JSON Schema syntax
422 `router id not unique`	Duplicate router IDs	Each router `id` must be unique within the tool
422 `dangling branch`	Branch missing exit	Set `nextRouterId` to a valid router ID or `"outputRouter"` on every branch
422 `_exportId not found` / `_importId not found`	Deleted or invalid resource	Verify the referenced export/import exists and has not been deleted
409 `tool in use`	Tool referenced by consumers	Remove tool from all flows, APIs, agents, and MCP servers before deleting
422 `dataType required`	Unnecessary routing fields	Remove `routeRecordsTo` / `routeRecordsUsing` from simple tools; the API defaults correctly

错误	原因	修复方案
422 `_integrationId required`	缺少集成	将 `_integrationId` 设置为有效的集成ID
422 `input.schema invalid`	JSON Schema无效	确保根Schema有 `type: "object"` 且符合JSON Schema语法
422 `router id not unique`	Router ID重复	工具内的每个router `id` 必须唯一
422 `dangling branch`	分支缺少出口	为每个分支设置 `nextRouterId` 为有效的router ID或 `"outputRouter"`
422 `_exportId not found` / `_importId not found`	资源已删除或无效	验证引用的导出/导入存在且未被删除
409 `tool in use`	工具被消费者引用	删除工具前，先从所有流程、API、Agent和MCP Server中移除该工具
422 `dataType required`	不必要的路由字段	从简单工具中移除 `routeRecordsTo` / `routeRecordsUsing` ；API会自动设置默认值
",

building-tools

Original

Translation

Building Tools

构建工具

Tool Concepts

工具核心概念

Tool Execution Pipeline

工具执行流水线

The Two Flavors of Lookup

两种查询类型

Consumer-Bound Connections

消费者绑定的连接

Quick Reference

快速参考

Decision Matrix

决策矩阵

Minimum Required Fields

必填字段

Which Schemas to Read

需参考的Schema

Schema Index

Schema索引

Related Skills

相关技能

How to Build a Tool

如何构建工具

1. Determine the tool's purpose

1. 确定工具用途

2. Identify the integration

2. 确定所属集成

3. Check for existing patterns

3. 检查现有模式

Search your account (fast, uses local index)

搜索你的账户（快速，使用本地索引）

Show what an existing tool uses (exports, imports, connections)

查看现有工具使用的资源（导出、导入、连接）

Find orphaned resources that could be reused

查找可复用的孤立资源

Check if similar tools already exist

检查是否已有类似工具

Search marketplace for pre-built integration templates

在市场中搜索预构建的集成模板

4. Build the connections, exports, and imports

4. 构建连接、导出和导入

5. Define the input schema

5. 定义输入Schema

6. Configure routing (if needed)

6. 配置路由（如有需要）

7. Wire page processors into branches

7. 将页面处理器接入分支

8. Configure output

8. 配置输出

9. Build the JSON

9. 构建JSON

Refactoring Steps into a Tool

将步骤重构为工具

CLI Commands

CLI命令

CRUD

CRUD操作

Manage page processors

管理页面处理器

Test run

测试运行

Debug (requires debug enabled on the underlying export/import)

调试（需要底层导出/导入启用调试）

Discovery

发现资源

Pre-Submit Checklist

提交前检查清单

Required (all tools)

必填项（所有工具）

Pipeline

流水线

Cross-resource consistency

跨资源一致性

Gotchas

注意事项

Common Errors