> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reygrid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tool calling

> Define tools on a chat request, send tool results back, and cancel tool calls.

You can expose **tools** (functions) to an agent on a chat request and send back **results** for tool calls.

## Define tools

`tools` is an array of `Tool` objects. Each has `type: "function"` and a `function` with:

| Field | Type | Required | Description |
| - | - | - | - |
| `name` | string | yes | Function name (minimum length 1) |
| `instructions` | string | no | When and how the function should be used |
| `parameters` | object | no | JSON Schema for the arguments |
| `strict` | boolean | no | Strict mode |

```json theme={"system"}
{
  "message": "Check my current subscription",
  "userId": "user_42",
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "check_subscription",
        "instructions": "Opens the customer's current subscription plan, renewal date, and payment status.",
        "parameters": {
          "type": "object",
          "properties": {
            "userId": { "type": "string", "description": "The customer's user id" }
          },
          "required": ["userId"]
        }
      }
    }
  ]
}
```

## Send results

`results` is an optional array (at least one item when present) of `{ toolCallId, output }` objects. `output` is a string, so serialize structured data as JSON.

```json theme={"system"}
{
  "message": "What is the status of my account?",
  "userId": "user_42",
  "tools": [ /* same tool definitions */ ],
  "results": [
    {
      "toolCallId": "call_xyz",
      "output": "{\"plan\":\"pro\",\"status\":\"active\"}"
    }
  ]
}
```

## Inspect tool calls

Messages returned by [List conversation messages](/api-reference/list-conversation-messages) can include `tool_calls`, each with an `id`, `function.name`, `function.arguments` (a string), and a `status`. Use the call `id` as `toolCallId`.

## Cancel a tool call

[`POST …/tool/cancel/{toolCallId}`](/api-reference/cancel-a-tool-call) cancels a tool call. It returns `404` if the tool call isn't found and `409` if it can't be canceled.

<Info>
  The OpenAPI specification does not describe how a non-streaming chat response signals that a tool call is requested (the response contains `output.reply` and `finish_reason` only), nor the possible `finish_reason` and `status` values. This page documents only what the specification and SDKs define.
</Info>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.