# RPC tool

Use `send_rpc_request` to let an Assistant perform actions in your WebRTC client during a conversation.

## Overview

The tool sends a Remote Procedure Call, or RPC, to the connected WebRTC client through LiveKit and returns the response string to the LLM.

You configure the RPC method, timeout, and payload schema through a `configuration` object when attaching the tool to an Assistant.

:::warning{title="WebRTC only"}

This tool is available only in WebRTC sessions. It is excluded from SIP sessions, including when the same Assistant handles both connection types.

:::

<Mermaid chart={`sequenceDiagram
    participant LLM
    participant Assistant
    participant Client as WebRTC Client

    LLM->>Assistant: calls update_cart(items, couponCode)
    Note over Assistant: Vocalise message while RPC runs (optional)
    Assistant->>Assistant: Serialise arguments to JSON payload
    Assistant->>Client: RPC "updateCart" with payload
    Client-->>Assistant: Response string
    Assistant-->>LLM: Response string`} />

***

## Naming and describing the tool

Set `nameOverride` and `descriptionOverride` to describe the action your client performs. The LLM sees these values in the tool schema and uses them to decide when to call the tool.

| Field                 | Type   | Required | LLM-facing | Description                                                                                 |
| --------------------- | ------ | -------- | ---------- | ------------------------------------------------------------------------------------------- |
| `nameOverride`        | string | No       | Yes        | Replaces the tool's function name as seen by the LLM. Should read like a function name.     |
| `descriptionOverride` | string | No       | Yes        | Replaces the tool's description as seen by the LLM. Should explain when and why to call it. |

### Writing effective overrides

The `nameOverride` should read like a function name: short, lowercase with underscores, and descriptive of the action (`update_cart`, `lock_screen`, `submit_order`). Avoid generic names like `do_action` or `call_rpc`.

In `descriptionOverride`, state when to call the tool and what result to expect.

**Example:**

```json
{
  "nameOverride": "update_cart",
  "descriptionOverride": "Updates the user's shopping cart. Call this tool when the user asks to add or remove items, or to apply a coupon code."
}
```

:::info{title="Where to set overrides"}

`nameOverride` and `descriptionOverride` are set at the tool-association level (alongside `assistantId`, `definitionId`, and `configuration`). They are not part of the `configuration` object itself.

:::

***

## Configuration schema

The `configuration` object you provide when attaching the tool to an Assistant accepts the following fields.

| Field            | Type                  | Required | Default | Description                                                                                                                           |
| ---------------- | --------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `method`         | string                | Yes      |         | RPC method name (e.g. `"updateCart"`). Also used as the default tool name.                                                            |
| `timeout`        | number                | No       | `10`    | Response timeout in seconds.                                                                                                          |
| `message`        | string                | No       |         | Text the agent vocalises while the RPC runs. The tool waits for both the response and playback. Supports `{variable}` resolution.                                                    |
| `payloadSchema`  | JSON Schema           | No       |         | Describes the RPC payload. Properties become the LLM-facing tool parameters.                                                          |
| `responseSchema` | JSON Schema or string | No       |         | Describes the expected response structure. Appended to the LLM-facing tool description so the model can interpret responses reliably. |

**Example:**

```json
{
  "method": "updateCart",
  "timeout": 5,
  "message": "Let me update your cart, one moment.",
  "payloadSchema": {
    "type": "object",
    "properties": {
      "items": {
        "type": "array",
        "description": "List of item IDs to add to the cart.",
        "items": { "type": "string" }
      },
      "couponCode": {
        "type": "string",
        "description": "Optional coupon code to apply."
      }
    },
    "required": ["items"]
  },
  "responseSchema": {
    "type": "object",
    "properties": {
      "success": { "type": "boolean", "description": "Whether the operation succeeded" },
      "cartTotal": { "type": "number", "description": "Updated cart total in the user's currency" },
      "itemCount": { "type": "integer", "description": "Number of items in the cart" }
    }
  }
}
```

***

## Payload schema

Define `payloadSchema` with JSON Schema keywords such as `type`, `properties`, and `required`. Its properties become the tool parameters that the LLM supplies.

### Defining parameters

Each property in `payloadSchema.properties` becomes a parameter the LLM can populate from the conversation. Use `description` fields to guide the model on what values to extract, and `required` to mark parameters that must be present for the RPC to succeed.

```json
{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "description": "List of item IDs to add to the cart.",
      "items": { "type": "string" }
    },
    "couponCode": {
      "type": "string",
      "description": "Optional coupon code to apply."
    }
  },
  "required": ["items"]
}
```

When no `payloadSchema` is provided, the tool takes no arguments and sends an empty `{}` payload to the client.

### Resulting LLM-facing tool

For the payload above with `descriptionOverride = "Updates the shopping cart. Use when the user wants to add or remove items."`, no `nameOverride`, and no `responseSchema`, the LLM-facing tool schema becomes:

```json
{
  "name": "updateCart",
  "description": "Updates the shopping cart. Use when the user wants to add or remove items.",
  "parameters": {
    "type": "object",
    "properties": {
      "items": {
        "type": "array",
        "description": "List of item IDs to add to the cart.",
        "items": { "type": "string" }
      },
      "couponCode": {
        "type": "string",
        "description": "Optional coupon code to apply."
      }
    },
    "required": ["items"],
    "additionalProperties": false
  }
}
```

***

## Response schema

Set `responseSchema` to describe the response fields the LLM should expect. The platform appends it to the tool description under "Response format:". Without it, the model receives the response string without a description of its structure.

### JSON schema format

Provide a standard JSON Schema object describing the response structure:

```json
{
  "responseSchema": {
    "type": "object",
    "properties": {
      "success": { "type": "boolean", "description": "Whether the operation succeeded" },
      "cartTotal": { "type": "number", "description": "Updated cart total in the user's currency" },
      "itemCount": { "type": "integer", "description": "Number of items in the cart" }
    }
  }
}
```

:::info{title="Description only"}

`responseSchema` describes the response but does not validate or transform it. The tool returns the response string, truncated after 5,000 characters when necessary.

:::

***

## Dynamic variables

Use `{variable}` placeholders in string values anywhere in `configuration`. The platform resolves them from [variables](/docs/variables) and [injected data](/docs/data-injection) when loading the configuration, before building the tool.

Reference injected data with the key `userFirstName` in `configuration.message`:

```json
{
  "method": "updateCart",
  "message": "Alright {userFirstName}, I'm updating your cart, one moment."
}
```

:::info{title="Unresolved variables"}

An unresolved `{variable}` placeholder becomes an empty string. The tool still attempts the RPC with the resulting configuration.

:::

***

## Limitations

| Constraint            | Limit                                                                       |
| --------------------- | --------------------------------------------------------------------------- |
| Connection type       | WebRTC only. The tool is not registered for Assistants using a SIP Channel. |
| Response size         | Truncated at 5 000 characters.                                              |
| Default timeout       | 10 seconds. Configurable via the `timeout` field.                           |
| Payload format        | JSON only. Arguments are serialised with `json.dumps`.                      |
| No client participant | Returns an error string if no WebRTC client is found in the room.           |
| Streaming responses   | Not supported. The full response is awaited before returning.               |

***

## Full example

Attach a shopping-cart tool to an Assistant. Fetch the `send_rpc_request` definition with `GET /data_next/ai/toolDefinitions?where={"name":"send_rpc_request"}` and use its `id` as `definitionId`. Replace the example Assistant ID and token with your own. Your connected WebRTC client must register an `updateCart` RPC handler that accepts this payload and returns a response string.

```http
POST https://newprd.reecall.io/data_next/ai/tools
Authorization: Bearer {token}
Content-Type: application/json
```

```json
{
  "definitionId": "b2c3d4e5-6789-4abc-9def-abc123456789",
  "assistantId": "<your-assistantId>",
  "nameOverride": "update_cart",
  "descriptionOverride": "Updates the user's shopping cart. Use this tool when the user asks to add items to their cart or apply a coupon code.",
  "configuration": {
    "method": "updateCart",
    "timeout": 5,
    "message": "Let me update your cart, one moment.",
    "payloadSchema": {
      "type": "object",
      "properties": {
        "items": {
          "type": "array",
          "description": "List of item IDs to add to the cart.",
          "items": {
            "type": "string"
          }
        },
        "couponCode": {
          "type": "string",
          "description": "Optional coupon code to apply."
        }
      },
      "required": [
        "items"
      ]
    },
    "responseSchema": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean",
          "description": "Whether the cart was updated"
        },
        "cartTotal": {
          "type": "number",
          "description": "Updated cart total"
        },
        "discount": {
          "type": "number",
          "description": "Discount applied from coupon"
        },
        "itemCount": {
          "type": "integer",
          "description": "Number of items in the cart"
        }
      }
    }
  }
}
```
