Building Tools

<!-- TIER:1 -->

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.

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.

Tool Execution Pipeline

When a tool is invoked:

1. Input received -- input data validated against the tool's JSON Schema (input)
2. Router evaluation -- routeRecordsUsing evaluates branch conditions (if multiple branches exist)
3. Branch selection -- matching branch processes the input
4. Page processors -- each processor executes sequentially (export lookups, import writes)
5. Response mapping -- responseMapping on each processor carries data to the next processor
6. Output mapping -- final output mapped according to the tool's output configuration (schema, mappings, lookups, hooks)
7. 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

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.

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.

Quick Reference

Decision Matrix

Minimum Required Fields

Every tool needs at minimum: name, _integrationId, and an input.schema.

Which Schemas to Read

1. Always: request.yml (base fields for create/update)
2. Input config: input.yml (schema, transform, mockInput)
3. Output config: output.yml (mappings, lookups, hooks)