Celigo tools overview

A Celigo tool is a reusable unit of integration logic with a defined JSON input and a defined JSON output. You build a tool once in Tool builder — a lookup that fetches a customer record, a decision that checks order eligibility, an import that posts a message — and then call it from flows, APIs, AI agents, MCP servers, and other tools without rebuilding the logic each time. This article explains what a tool is made of, where it can run, how it behaves in each place, and how the platform helps you govern tools across your account. It's for anyone building integrations, APIs, or AI agents in integrator.io, and for account administrators who manage shared resources.

Access Tools using any of the following paths:

• AI studio > Tools
• Build > Tools
• Open an integration > select the Tools tab at the top of the integration.

What a tool is

A tool has three parts, shown left to right on the Tool builder canvas:

• Tool input — The JSON schema a caller must satisfy. Every record passed to the tool is validated against this schema before the tool runs.
• Logic steps — One or more lookups, imports, nested tools, AI agents, or guardrails, optionally organized with branching. These do the work, using connections the caller supplies.
• Tool output — The JSON schema the tool returns. The result of the logic steps is mapped into this schema and validated before it's returned to the caller.

Because the input and output are schemas, a tool behaves the same way wherever it's called: input that doesn't match the input schema is rejected, and a result that doesn't match the output schema stops the run with an error. For the schema editor and its validation options, see Tool schema and validation reference.

A tool always belongs to an integration. As a best practice, keep tools that several flows or agents share in a dedicated integration (for example, one named "Core tools") so you can find and promote them together.

Where a tool can run

A tool can be called from five places. The calling resource always supplies the connections the tool uses, so the same tool can run against different accounts or environments depending on who calls it. For how connections are supplied, see Use a tool in flows, APIs, AI agents, and MCP servers.

For invocation logs and trace views, see View tool invocation logs.

How a tool run works

Every run validates the caller's record against the input schema, runs the logic steps, and validates the result against the output schema before returning it; a mismatch at either end stops the run with an error. For the full sequence and what the caller receives, see Use a tool in flows, APIs, AI agents, and MCP servers. If a logic step fails, the step's error handling setting decides whether the run stops or continues — see Add lookups and imports to a tool.

Governance

Tools are shared resources, so the platform tracks who depends on them:

• Used by — Lists every flow, API, agent, MCP server, and tool that references the tool. Available from the Tools page and from the Tool builder header.
• Deletion safeguards — You can't delete a tool while another resource references it. A deleted tool stays in the recycle bin for 30 days, or until your data retention policy removes it. See Delete a tool.
• Audit log — Every change to a tool and its steps is recorded on the tool's Audit log tab. See Tool builder reference.
• Promotion — Tools move between environments with the flows and agents that use them, through cloning, download and upload, or integration lifecycle management (ILM). See Promote tools with ILM.

Permissions

Account owners, administrators, and users with Manage access to the tool’s integration can edit, move, and delete tools and delete their logs. Moving a tool also requires Manage access to the destination integration.

Example tools

Tools work best for logic that several callers need in the same form:

• Customer lookup — Takes a customer ID or email, looks it up in your CRM, and returns the normalized record. Used by an onboarding flow, a support agent, and an order API.
• Provisioning decision — Takes a signup record and returns whether to create a trial, a paid account, or a review task, based on rules you keep in one place.
• Order eligibility — Takes an order and returns whether it qualifies for free shipping or a promotion, so every channel applies the same rules.
• GL account mapper — Takes a transaction and returns the general ledger account to post it to.
• Ticket summary fetcher — Takes a ticket ID, retrieves the ticket and its comments, and returns a summary an AI agent can act on.

For help deciding whether to build logic as a tool or as an API, see Tools vs. APIs: how to choose.

Tool lifecycle

Related articles

• Tools vs. APIs: how to choose
• Create a tool
• Tool builder reference
• Tool schema and validation reference
• Use a tool in flows, APIs, AI agents, and MCP servers