<!-- SPDX-License-Identifier: Apache-2.0 -->

# Tool reference

Agents interact with the runtime through tools. The full built-in tool list and enablement configuration are documented in [Tool configuration](../configuration/tools.md).

This page details the `respond` tool, the primary way an agent communicates with users.

## respond

Sends a message to the current or another channel, with optional file attachments.

### Parameters

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `content` | string | Yes | — | Message content in Markdown. |
| `channel` | string | No | `"current"` | Target channel for the message. |
| `attachments` | string[] | No | — | Sandbox file paths to attach, e.g. `["/workspace/report.pdf"]`. |
| `final` | boolean | No | `true` | Whether this is the final message of the turn; `false` sends an intermediate status update. |

### Channel resolution

| Value | Description |
| --- | --- |
| `"current"` (default) | Send to the current conversation. |
| `"last"` | Send to the most recently active session. |
| `"owner"` | Send a DM to the bot owner; requires `ownerId` to be configured. |
| Explicit session id | Send to a specific session, e.g. `"discord:123456789\|987654321"`. |

### Notes

- Attachments work only on platforms that support them (Discord; internal sessions do not).
- Cross-channel sends to a different session mark the response as not final.

### Return value

```json
{
  "final": true,
  "sent": true
}
```

### Examples

Send a final reply to the current channel:

```json
{
  "content": "Here's the information you requested.",
  "final": true
}
```

Send an intermediate status update:

```json
{
  "content": "Looking into that for you...",
  "final": false
}
```

Send a DM to the bot owner:

```json
{
  "content": "Alert: Something needs attention",
  "channel": "owner"
}
```

Send with file attachments:

```json
{
  "content": "Here's the report you asked for",
  "attachments": ["/workspace/report.pdf", "/workspace/data.csv"]
}
```