> For the complete documentation index, see [llms.txt](https://developer.celigo.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.celigo.com/mcp/tools.md).

# Tools

## Tools

Celigo Platform MCP exposes a compact, composable toolset. Your client fetches the full list and JSON schemas at runtime via the MCP `tools/list` method, so the catalog is always current and you never configure individual tools. You also never call them by hand: you ask in plain language and the agent chooses and chains the tools. This page explains the model and lists every tool, with the kind of prompt that triggers each group.

### The model

Rather than one tool per CRUD verb, the catalog is built from three patterns:

* **`list_*` reads.** Each resource has one reader that does double duty: omit `_id` to list a collection, or set `_id` to fetch one full resource. So `list_flows` lists flows, and `list_flows` with an `_id` returns that flow with all its steps. List responses use a compact summary projection you can widen or narrow with `include` and `exclude`.
* **`upsert_*` writes.** One writer per resource. Omit `_id` to create (POST, the server assigns the id); provide `_id` to update (PUT, a full-document replace). Read the resource first, change the fields you want, write the whole document back.
* **`delete_resource`.** One generic delete for every resource family, chosen with `resourceType`. It runs a dependency pre-flight and returns warnings for anything that still references the resource.

A few operation tools sit outside the pattern: `run_flow`, `list_jobs` and `cancel_job`, the error-triage tools, the lookup-cache-data tools, `get_schema`, and `kb_answer`. They are all in the catalog below.

Why this shape: collapsing list and get into one tool, and create and update into one tool, keeps the catalog small and mirrors how agents actually work. They list to find an `_id`, then act on it. Fewer tools means less to load and less to get wrong.

### Fetching schemas on demand with `get_schema`

Resource and connector schemas are large, so they are not bundled into `tools/list`. Instead, the agent calls `get_schema` to pull only what it needs, when it needs it. It takes a `target` and a `name`:

* `target: "resource"` returns the shape of a platform resource (`flow`, `export`, `connection`, and so on). Use `resource/sub` for adaptor-specific shapes like `connection/netsuite`.
* `target: "connector"` returns an HTTP connector's definition by id or partial-name search, or native application metadata (record types and fields) when `name` is a connection `_id`, for example a NetSuite or Salesforce connection.
* `target: "connector_openapi"` returns the OpenAPI fragment for an HTTP connector's REST surface.

A good build loop is: `get_schema` to learn the fields, construct the body, then `upsert_*`. That avoids guessing field names and burning calls on `422` validation errors. The schemas come from the same OpenAPI specs published in the [API reference](https://developer.celigo.com/api).

### Automatic composition

Agents chain tools on their own. Ask for flow details and the agent calls `list_flows` with the flow `_id`, sees the export and import references in the response, then calls `list_exports` and `list_imports` to resolve them, building a full picture without being told each step.

***

## Catalog

Every tool the server exposes, grouped by what it does. `list_*` and `get_schema` and `kb_answer` are **reads**. `upsert_*`, `delete_resource`, `run_flow`, `cancel_job`, `triage_flow_errors`, and the `*_lookup_cache_data` writers **change live data**, so a careful agent confirms before calling them.

### Resources

> Ask: *"List my flows."* / *"Show me the NetSuite connection."* / *"Create an export that pulls Shopify orders."*

Every family has a `list_*` reader and an `upsert_*` writer, working on the resources you already know from integrator.io.

| Resource      | Tools                                      | What it is                                                                                                                           |
| ------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| Connections   | `list_connections` `upsert_connection`     | Credentials and config for one external system (NetSuite, Salesforce, an HTTP API, a database, SFTP). Shared by exports and imports. |
| iClients      | `list_iclients` `upsert_iclient`           | A reusable OAuth2 app registration (client id and secret) that connections use for OAuth.                                            |
| Integrations  | `list_integrations` `upsert_integration`   | The top-level project that groups related flows, connections, and settings.                                                          |
| Flows         | `list_flows` `upsert_flow`                 | A pipeline that moves data from a source export to a destination import, on a schedule or a trigger.                                 |
| Exports       | `list_exports` `upsert_export`             | The source step that reads records out of a connection.                                                                              |
| Imports       | `list_imports` `upsert_import`             | The destination step that writes records into a connection.                                                                          |
| AI Agents     | `list_agents` `upsert_agent`               | An LLM-powered import step that classifies, extracts, or generates data inside a flow.                                               |
| Guardrails    | `list_guardrails` `upsert_guardrail`       | A safety check (PII detection, content moderation) that validates data moving through a flow.                                        |
| Scripts       | `list_scripts` `upsert_script`             | A JavaScript hook that transforms data or makes decisions during a flow run.                                                         |
| APIs          | `list_apis` `upsert_api`                   | A custom HTTP endpoint you expose to external callers.                                                                               |
| Tools         | `list_tools` `upsert_tool`                 | A reusable building block (lookup, import, transform) callable from flows, APIs, and agents.                                         |
| MCP Servers   | `list_mcp_servers` `upsert_mcp_server`     | A customer-built MCP endpoint that exposes your Tools and APIs (the `mcpServers` resource, not this server).                         |
| Lookup Caches | `list_lookup_caches` `upsert_lookup_cache` | An in-memory key-value store for fast lookups and deduplication during a flow run.                                                   |

**Good to know**

* **`list_*` does double duty.** No `_id` lists the collection (with `cursor` / `limit` to page and `include` / `exclude` to shape fields); an `_id` returns that one full resource. A few add filters: connections by `type`, flows by `_abstractFlowId`, tools by `_integrationId`.
* **`upsert_*` with an `_id` is a full replace.** Read the resource first, change the fields you want, and send the whole document back, or omitted fields are cleared.
* **Credentials never round-trip.** Reads mask secrets on connections and iClients as `******`. A write that still contains that mask is rejected unless you pass `force: true`, so you cannot accidentally overwrite a real secret with the mask.
* **New flows start disabled.** Create flows with `disabled: true` and enable them only after the mappings and connections check out.

### Run flows and inspect jobs

> Ask: *"Run the daily inventory sync and tell me what happened."*

| Tool         | Read/Write | Description                                                                                                                                                              |
| ------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `run_flow`   | write      | Trigger an immediate run; returns a `jobId`. The flow must be enabled.                                                                                                   |
| `list_jobs`  | read       | Omit `_id` to list jobs (pass a scope filter like `_flowId`, `_integrationId`, or a date bound); set `_id` to a parent job to get the parent plus per-step `children[]`. |
| `cancel_job` | write      | Cancel a running job mid-flight.                                                                                                                                         |

### Triage errors

> Ask: *"Show the open errors on that import, then retry the timeouts."*

| Tool                           | Read/Write | Description                                                                                                                            |
| ------------------------------ | ---------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `list_flow_errors`             | read       | Open errors for a flow step (`_id` flow + `_stepId`). Each has `errorId`, `message`, `code`, `traceKey`, `retryDataKey`, `occurredAt`. |
| `get_flow_error_retry_data`    | read       | The stored retry snapshot for one error (`retryDataKey`).                                                                              |
| `update_flow_error_retry_data` | write      | Full-replace that snapshot to fix a staged payload before retrying. Does not reprocess.                                                |
| `triage_flow_errors`           | write      | One action on a step's errors: `retry` (writes to destinations), `resolve`, `tag` (codes from `list_tags`), or `assign` (by email).    |
| `list_tags`                    | read       | Error tags in the account; use each `tagId` short code with `triage_flow_errors`.                                                      |

### Lookup cache data

> Ask: *"What is cached under the customer-xref keys?"*

| Tool                       | Read/Write | Description                                                                                                 |
| -------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------- |
| `list_lookup_cache_data`   | read       | Read entries. Filter with `key`, `keys`, or `startsWith`; omit all for the first page (about 1000 entries). |
| `upsert_lookup_cache_data` | write      | Load or replace entries (`body: { data: [{ key, value }] }`). Auto-batches in groups of 1000.               |
| `delete_lookup_cache_data` | write      | Remove entries by `key` / `keys`, or omit both to purge all entries (the cache resource stays).             |

### Account and utilities

> Ask: *"Who changed the order flow last week?"* / *"What environments are on this account?"*

| Tool                     | Read/Write | Description                                                                                                                               |
| ------------------------ | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `list_environments`      | read       | Sandbox and staging environments on the account.                                                                                          |
| `list_audit_log_entries` | read       | Audit log, newest first, with `fieldChanges[]`. Filter by `resourceType`, `_resourceId`, `_byUserId`, `action`, `source`, and date range. |
| `delete_resource`        | write      | Delete by `resourceType` and `_id` across all resource families. Returns `{ deleted, id, warnings, response }`.                           |

### Schema and knowledge

> Ask: *"What fields does a NetSuite connection need?"* / *"How do delta exports work?"*

| Tool         | Read/Write | Description                                                                                                                                                 |
| ------------ | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `get_schema` | read       | Fetch resource and connector schemas on demand. See [The model](#fetching-schemas-on-demand-with-get_schema) above.                                         |
| `kb_answer`  | read       | Ask a natural-language question and get an answer from the Celigo Knowledge Base. Supports follow-ups via `thread_id` and location-aware answers via `url`. |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.celigo.com/mcp/tools.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.