Tools and custom APIs both package integration logic you can call on demand, but they solve different problems: a tool is reusable logic for callers inside integrator.io, and an API is an HTTP endpoint for callers outside it. This article is for builders and API developers deciding how to package a piece of logic. It gives you the decision criteria, the characteristics of each, and the recommended pattern when you need both. For what a tool is, see Celigo tools overview.
Recommended pattern
Build the logic as a tool. If an external system needs to call it over HTTP, create an API in API builder that invokes the tool. That way the logic lives in one place, every internal caller reuses it, and the API adds only the HTTP layer (request shape, response codes, authentication).
Decision table
| You need to… | Build a tool | Build an API |
|---|---|---|
| Reuse the same logic in several flows, agents, or MCP servers | Yes | No |
| Call the logic from a flow or an AI agent | Yes | Through a flow's HTTP step only |
| Expose an endpoint that external systems call | No — wrap it in an API | Yes |
| Control the HTTP request shape (method, path, headers, query) | No | Yes |
| Return custom HTTP status codes and error bodies | No | Yes |
| Rely on retries and queueing | Yes, when called from a flow | No |
| Run longer than two minutes | Yes, when called from a flow | No — APIs time out after two minutes |
When to build a tool
Build a tool when the logic is internal and reusable: a lookup several flows need, a decision an agent and a flow both make, or a multi-step operation you want to version in one place. A tool:
- Has one JSON input and one JSON output, both defined by schemas.
- Has no HTTP configuration and no custom error responses — it returns an errors array to the caller.
- Runs in batch with retries when a flow calls it, and synchronously when an API, agent, MCP server, or another tool calls it.
- Uses the connections its caller supplies, so it can run against different accounts without changes. See Use a tool in flows, APIs, AI agents, and MCP servers.
When to build an API
Build an API when something outside integrator.io needs to call the logic over HTTP, or when you need control over the HTTP exchange itself. An API:
- Defines one request and one or more responses, including status codes and error bodies.
- Runs synchronously and times out after two minutes.
- Has no internal retries.
- Can invoke a tool as a step, so the logic stays reusable.
API calls are billable. Tool calls made by an AI agent count as AI agent actions, and tool calls through an MCP server count as MCP calls. See Track your AI agent actions and credits usage and Track your MCP call usage.