# Calling a connector

Every connector — REST or RPC — is reached through the same three tools. They are exposed as native agent tools and over the [MCP server](/docs/mcp). The flow is always: discover the catalog, read the service passport, then execute.

### list_services — the catalog

Returns the connector catalog: a canonical `key` and one-line summary per service. Handshake-sized (~2–5 KB), so every session can start here. With connected accounts, each entry is tagged `connected: true/false`.

### describe_service — the passport

Returns a structured **passport** for one service: its modules, common recipes (concrete `VERB /path` examples with body templates), rate limits, field hints, pagination hints, enums, response examples, and a `version`/`ttl` for client-side caching. Call it without a `module` for the index, then with a `module` for the full per-module spec.

```bash
describe_service(service="wildberries")
describe_service(service="wildberries", module="statistics")
```

### connector_execute — the call

A single executor for any connector. Arguments are validated against the service schema **before** any outbound HTTP call.

```bash
connector_execute(
  service="wildberries",
  module="statistics",
  method="GET",
  path="/api/v1/supplier/orders",
  query={"dateFrom": "2026-04-15"}
)
```

## connector_execute parameters

<ParamTable rows={[
  { name: "service", type: "string", required: true, description: "Connector key from list_services (for example wildberries). May carry an account suffix — see multi-account addressing below." },
  { name: "module", type: "string", description: "Sub-area of the connector (statistics, content, …) as listed in the passport." },
  { name: "method", type: "string", required: true, description: "REST: the HTTP verb (GET/POST/…). RPC: the RPC method name." },
  { name: "path", type: "string", description: "REST: the request path. RPC: leave empty and pass the method name in method." },
  { name: "body", type: "object", description: "Request body for write calls." },
  { name: "query", type: "object", description: "Query-string parameters for the call." },
  { name: "instance_id", type: "string", description: "Target a specific connected account when more than one is connected." },
]} />

## REST vs RPC

Connectors come in two shapes, and `connector_execute` handles both:

- **REST** (most connectors) — pass `module`, an HTTP `method`, a `path`, and `body`/`query`.
- **RPC** (for example `bitrix24`, the `onec` family) — leave `path` empty and pass the RPC method name in `method`.

The passport's recipes show the exact shape for each connector, so you rarely guess.

## Multi-account addressing

When an organization has connected more than one account for a service (several Ozon cabinets, for instance), address a specific one. A **bare service** name fans reads across all connected accounts; **writes must name one**, either via `instance_id` or a suffix on the service:

```bash
connector_execute(service="ozon:Top Zip", method="POST", path="/v1/product/import", body={ ... })
```

## Did-you-mean recovery

Calls don't fail silently on a near-miss. Recipes are examples, not a whitelist, so:

- An unknown **module** returns a hard error with `did_you_mean` suggestions and the list of `known_modules`.
- An unknown or mismatched **path** still proceeds, but attaches a soft `path_did_you_mean` hint plus an `available_paths` menu in the response metadata.
- An unknown **account** returns `UNKNOWN_INSTANCE` with a `candidates` list.

## Errors

Connector calls return the standard tool error contract — `code`, `message`, `retryable`, and an optional `hint`. Calls made over MCP carry no HTTP status code. See [the MCP error table](/docs/mcp) and [Errors & rate limits](/docs/reference).