> 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`. For connections it runs a dependency pre-flight and returns any dependents as advisory `warnings[]`; every other type deletes immediately with no scan. Either way the delete always proceeds — it never blocks.

A few operation tools sit outside the pattern: `run_flow`, `list_jobs` and `cancel_job`, the error-triage tools, the execution-log reader, the lookup-cache-data tools, the EDI transaction tools, the marketplace pair, `get_schema`, and `search_knowledge_base`. 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.

Every tool also declares standard [MCP tool annotations](https://modelcontextprotocol.io/specification/2025-06-18/server/tools) (read-only, destructive, idempotent), so clients that understand them badge reads and writes correctly and can ask for confirmation before destructive calls.

### 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 Unprocessable Entity` 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_*`, `get_*`, and `search_knowledge_base` are **reads**. `upsert_*`, `delete_resource`, `run_flow`, `cancel_job`, `triage_flow_errors`, `update_edi_fa_status`, `deploy_template`, and the `*_lookup_cache_data` writers **change live data**, so a careful agent confirms before calling them.

> ⚠️ **Writes act on your real account, and `delete_resource` never blocks.** `upsert_*`, `run_flow`, `triage_flow_errors`, `deploy_template`, and the `*_lookup_cache_data` writers change live data. `delete_resource` removes the target even when other resources depend on it — for connections, dependents come back only as advisory `warnings[]`; other types are deleted with no dependency scan at all. Confirm the agent's plan before any write.

### 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_ai_agents` `upsert_ai_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.                                                                                                |
| EDI Profiles     | `list_edi_profiles` `upsert_edi_profile`         | The interchange envelope for a trading partner (X12 ISA/GS or EDIFACT UNB): sender and receiver IDs, qualifiers, standards versions, control numbers. Required for B2B EDI flows. |
| File Definitions | `list_file_definitions` `upsert_file_definition` | Parsing and generation rules for structured files (CSV, fixed-width, X12, EDIFACT) that file-based exports and imports reference.                                                 |

**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: flows by `_abstractFlowId` or open-error state (`hasOpenErrors`, `numError_gte`), tools by `_integrationId`, and most resources by `externalId`.
* **`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."* / *"Re-run yesterday's window for just the orders export."*

| Tool                  | Read/Write | Description                                                                                                                                                                                                                                                                                                                                        |
| --------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `run_flow`            | write      | Trigger an immediate run; returns a `_jobId`. The flow must be enabled. An optional `body` targets the run: `export.startDate` / `export.endDate` override the delta window for backfills, and `_exportIds` runs only specific source exports.                                                                                                     |
| `list_jobs`           | read       | Omit `_id` to list jobs (always pass at least one scope filter — `_flowId`, `_integrationId`, or a date bound — as unscoped lists are slow or rejected); set `_id` to a parent job to get the parent plus per-step `children[]`. Add `includeFiles: true` with `_id` to attach short-lived presigned download URLs for any files the run produced. |
| `cancel_job`          | write      | Cancel a running job mid-flight.                                                                                                                                                                                                                                                                                                                   |
| `list_execution_logs` | read       | Step-by-step debug logs for one run (`_id` flow + `_jobId`; the flow needs debug logging armed). Alone it returns the log index; add `recordId` and `groupId` for one record's step timeline; add `stage` for the actual request and response payloads at that stage.                                                                              |

### Triage errors

> Ask: *"Where are the errors across my account?"* / *"Show the open errors on that import, then retry the timeouts."*

Start wide, then drill in: `list_flow_errors` with no arguments returns an account-wide summary of every erroring flow and step, and `list_flows` with `hasOpenErrors: true` (or `includeErrorCounts: true`) surfaces the flows that need attention, sorted by open-error count.

| Tool                           | Read/Write | Description                                                                                                                                                                                                                                                                  |
| ------------------------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_flow_errors`             | read       | Open errors at any scope. No arguments: account-wide summary (`totalErrors`, affected flows and steps). `_id`: one flow's errors grouped by step. `_id` + `_stepId`: one step's full error objects — `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).             |

### B2B EDI transactions

> Ask: *"Did the 850s from Acme land yesterday, and were any acknowledgments rejected?"*

The transaction log for [B2B Manager](https://docs.celigo.com/hc/en-us/articles/28037678084123-Getting-started-with-EDI-B2B-Manager) EDI exchange. The EDI *building blocks* — profiles and file definitions — are regular resources in the table above; these two tools cover the runtime side.

| Tool                    | Read/Write | Description                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ----------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_edi_transactions` | read       | Query the EDI transaction log. Filter by `fileType` (`X12`, the default, or `EDIFACT`), `documentType` (a document code like `"850"` or `"ORDERS"` — not the family name), `direction`, `documentNumber`, `_integrationId`, and a date window; or set `_id` for one transaction. `includeFaDetails` / `includeMdn` fetch acknowledgment detail per returned row — an extra API call each, so keep `limit` small when you use them. |
| `update_edi_fa_status`  | write      | Set functional-acknowledgment status on a batch of transactions. Only `accepted` and `rejected` are writable; other statuses are system-managed.                                                                                                                                                                                                                                                                                   |

### Marketplace templates

> Ask: *"Install the Shopify to NetSuite template and wire it to my existing connections."*

| Tool               | Read/Write | Description                                                                                                                                                                                                                                                      |
| ------------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_marketplace` | read       | Browse the published marketplace catalog (templates by default, sorted by installs), or set `_id` to preview one template's full blueprint — every resource the install would create. The preview doubles as a source of working example configs while building. |
| `deploy_template`  | write      | Install a template into a new integration. Requires a `connectionMap` pairing each connection in the template's preview with a real connection `_id` in your account.                                                                                            |

### 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 }`. For connections, `warnings` lists dependents; every other type deletes immediately with no dependency scan. Warnings never block the delete. |

### 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 [Fetching schemas on demand](#fetching-schemas-on-demand-with-get_schema) above.                        |
| `search_knowledge_base` | 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`. |

***

## Beyond tools: prompts and resources

The server exposes two more MCP primitives alongside its tools. Both are open-sourced in [`celigo/ai`](https://github.com/celigo/ai) and loaded by the server, so the catalog stays in sync with the prompts and reference material.

**How your client surfaces these.** Tools are model-controlled — every client hands them to the agent automatically. Prompts and resources are *user*-controlled, so clients expose them as explicit affordances rather than agent tools, and where they appear differs by client:

* **Claude Code** — run `/mcp` to browse them; invoke a prompt as a slash command (`/mcp__celigo__plan-new-integration`); attach a resource with an `@` mention.
* **Claude Desktop** — add them from the **+** (add context) menu.
* **Cursor** — all three appear together in the MCP settings panel.

If a client only shows the tool list, the prompts and resources aren't missing — they're reached through these user actions.

### Guided prompts

Multi-step playbooks your client can invoke directly — in Claude Code and Claude Desktop they show up as slash commands. Each one composes the tools above into a workflow.

| Prompt                 | What it guides                                                                           | Arguments                                |
| ---------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------- |
| `getting-started`      | Orient in an account: core concepts, build order, and which prompt to use next.          | —                                        |
| `audit-account-health` | Count resources, find erroring flows and offline connections, return a prioritized list. | —                                        |
| `troubleshoot-flow`    | Diagnose a failing flow from its latest job and step errors.                             | `flowId` (optional)                      |
| `diagnose-connection`  | Diagnose a failing or offline connection.                                                | `connectionId` (optional)                |
| `review-flow-config`   | Review a flow's mappings, connections, and steps for problems.                           | `flowId` (optional)                      |
| `plan-new-integration` | Plan a new integration between two applications.                                         | `sourceApp`, `destinationApp` (optional) |
| `writing-handlebars`   | Author Handlebars expressions for mappings, HTTP bodies, SQL, URIs, and filters.         | —                                        |
| `writing-sql`          | Author SQL for RDBMS exports and imports.                                                | —                                        |

### Reference resources

Static context the agent reads on demand, under the `celigo://resources/...` URI scheme.

| Resource                | Content                                                                                 |
| ----------------------- | --------------------------------------------------------------------------------------- |
| Product glossary        | Official Celigo terminology and definitions.                                            |
| Tool usage guide        | How to approach common tasks and which tools to chain.                                  |
| Error pattern reference | Common error codes, their causes, and typical resolutions.                              |
| Connector catalog       | Supported connection types, HTTP connectors, trading-partner connectors, and templates. |
| API reference           | Overview of the REST API by resource, linking to the full OpenAPI spec.                 |

Connector and resource *schemas* are not resources — fetch those with the `get_schema` tool.


---

# 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.