Articles in this section

Use a tool in flows, APIs, AI agents, and MCP servers

Teena Killa
Updated

A tool runs wherever it's called — as a Tool step in a flow or API, as a capability of an AI agent or MCP server, as a nested step inside another tool, or directly through Celigo's REST API — and behaves the same way in each place. This article explains what happens at runtime, how the calling resource supplies the connections the tool uses, and what's specific to each kind of caller. It's for integrator.io users adding a tool to a flow or API, and for AI agent and MCP server builders exposing a tool to a model. For what a tool is, see Celigo tools overview.

Important

Prerequisites: A tested tool. See Test a tool in Tool builder.

What happens at runtime

For every record a caller sends:

  1. The record is validated against the tool input schema. A record that doesn't match is rejected with an error that names the property.
  2. The tool's steps run, following its branching and error handling.
  3. The result is validated against the tool output schema and returned. A result that doesn't match stops the step with an error.

In a flow, records are processed in batch, and a tool error follows the flow's retry and error handling. In an API, AI agent, MCP server, nested tool, or REST API call, the tool runs synchronously and the error is returned to the caller.

Connection overrides

A tool declares which connections its steps use, but it doesn't own them at runtime: the calling resource binds a connection of its own for each one. That's what lets one tool run against different accounts or environments in different callers. The rules:

  • Every connection the tool uses must be bound by the caller, including connections used by nested tools. If one is missing, the run fails.
  • Binding a connection in a caller doesn't change the tool or any other caller.
  • When you clone or promote a tool, the connections are chosen again at the destination. See Clone a tool and Promote tools with ILM.

Add a Tool step

  1. Open the flow in flow builder or the API in API builder.
  2. Select Add step after the step that produces the records to send, and then select Add tool.
  3. Select the tool from the pre-built tools, or enter Name your tool and a Description to build a new one, and then select Next.
  4. For each connection the tool requires, select the connection this flow or API should use.
  5. Select Preview to view the input data that will be sent to the tool. Preview does not execute the tool or apply mock data. To run the tool and view its actual output before saving, select Send.

The flow passes each record into the tool, waits for it to run, and receives the tool's output for the following steps. Results appear in the flow's run logs or the API's logs, with a trace view of the tool's steps. See View flow run logs and View API request and execution logs.

Add a tool to a tool

A tool can call another tool as a step, up to five levels deep.

  1. On the outer tool's canvas, select Add step, and then select Add tool.
  2. Enter Name your tool and a Description for the step, or select one of the pre-built tools listed under Optionally choose from pre-built tools. Filter by Source or sort by Similarity score to find one.
  3. Select Next, and then map the outer record into the nested tool's input.

The nested tool's connections are bound by whichever resource calls the outer tool. Its steps appear inline in trace views.

Add a tool to an AI agent

An AI agent chooses when to call a tool based on the tool's Description and its input schema, so write both for the model: say what the tool does, what it returns, and describe each input property. For the steps to attach the tool and bind its connections, see Create an AI agent.

Check the agent's model provider against the keywords in the tool's schemas — see Tool schema and validation reference.

Add a tool to an MCP server

An MCP server exposes the tool to any MCP client. For the steps to add it and bind connections, see Create MCP servers. Two settings are specific to MCP:

  • Tool name — The name clients see. It must be 1–128 characters, unique within the server, and contain only letters, digits, _, -, and .; no spaces or commas. Names are case-sensitive.
  • Annotations — Hints that tell clients how the tool behaves. Each is true or false.
Annotation Set it to true when
readOnlyHint The tool only reads data.
destructiveHint Indicates whether the tool can delete or overwrite data. When true (the default), the tool may perform destructive updates to its environment; when false, it only adds data. This hint applies only to tools that modify data (readOnlyHint: false); it has no meaning for read-only tools.
idempotentHint Indicates whether calling the tool more than once with the same input has the same effect as calling it once. When true, repeated calls make no further changes; when false, each call can change the environment again. This hint applies only to tools that modify data (readOnlyHint: false); it has no meaning for read-only tools.
openWorldHint The tool reaches systems outside your account.

Call a tool through the REST API

Any application can invoke a tool directly with an API token through Celigo's REST API. The caller sends a JSON body that satisfies the input schema and receives the tool output or an errors array. These calls appear in the tool's Logs tab with the resource type Standalone, attributed to the token's owner. For the endpoint and authentication, see Tools in the integrator.io API reference.

Related articles