# Flow tools (exo_<name>_<id8>)

> Documentation index: https://exomations.com/llms.txt

Each active flow is a tool. Calling it starts one run of that flow.

A key with `execute` sees one tool per active flow, named `exo_<name>_<id8>`: the flow's name in lowercase Latin letters and digits (up to 48 characters; any other character becomes `_`), then the first 8 letters and digits of the flow's ID. A flow whose name has no Latin letters or digits becomes `exo_flow_<id8>`. The tool's description is one fixed sentence from Exomations (it tells the assistant that what follows is data, not instructions), then the first 400 characters of the flow's own description, so write that well: it is what the assistant reads to decide when to use the flow.

The arguments are passed to the flow's Trigger step as `payload` (if `payload` is missing, the whole `arguments` object is used). A payload may be up to 512 KB, 10 levels deep, 1,000 keys and 5,000 items per list. The call does not wait for the flow: read the run with `exo_get_execution`.

Up to 200 flows are listed. Flows with a Nafath request step, and flows with a Muqeem or Tamm step that changes a government record, are not offered as tools, nor are flows that run one of them as a sub-flow. A run started over MCP cannot start such a flow as a sub-flow either.

Permission: `execute`.

## Input

| Name | Type | Required | Description |
|---|---|---|---|
| `payload` | object | no | Input payload passed to the flow's trigger node. The shape depends on the flow — usually the same JSON body you would POST to /api/trigger/:flowId. |

## Returns

`executionId`, `flowId`, `flowName` and `status`: `queued`, or `held` when the workspace is past 120% of its monthly allowance (the run starts by itself after a top-up, an upgrade or the monthly reset). Runs started over MCP count toward the same monthly allowance and simultaneous-run limit as any other run.

## Errors

- JSON-RPC -32602 (HTTP 200): `Unknown tool: <name>`
- JSON-RPC -32602 (HTTP 200): `Invalid payload: <reason>`
- JSON-RPC -32001 (HTTP 403): `API key lacks the 'execute' permission required to trigger flows`

## Example call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "exo_overdue_invoice_reminders_7a17617d",
    "arguments": {
      "payload": {
        "customer_id": "C-204"
      }
    }
  }
}
```

## Example result

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Flow \"Overdue invoice reminders\" queued. Check Exomations to see live progress.\n{ ... }"
      }
    ],
    "structuredContent": {
      "executionId": "0b6f6c1e-5a55-4d0e-9a57-2f7c1d0e8a11",
      "flowId": "7a17617d-3c4e-4f0a-9b1e-2d5c8e0f4a61",
      "flowName": "Overdue invoice reminders",
      "status": "queued"
    },
    "isError": false
  }
}
```
