---
title: Agent Tools
description: Reference for the two Agent Receipts tools the OpenClaw agent can call — ar_query_receipts and ar_verify_chain.
---

The `@agnt-rcpt/openclaw` plugin registers two tools that the OpenClaw agent can call directly during a session:

| Tool | Purpose |
|------|---------|
| `ar_query_receipts` | Query and summarise receipts from the current or past sessions |
| `ar_verify_chain`   | Verify the cryptographic integrity of a receipt chain |

These tools are not visible by default. See [Installation: Tool visibility](/openclaw/installation/#tool-visibility) for the `alsoAllow` config required to expose them to the agent.

---

## `ar_query_receipts`

Returns a summary of receipts matching the given filters, including breakdowns by risk level, outcome status, and action type.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `action_type` | string (optional) | Filter by action type, e.g. `filesystem.file.read` |
| `risk_level`  | string (optional) | Filter by risk level: `low`, `medium`, `high`, `critical` |
| `status`      | string (optional) | Filter by outcome: `success` or `failure` |
| `limit`       | number (optional) | Maximum number of results to include |
| `session_id`  | string (optional) | Restrict to a specific session; defaults to the current session |

All parameters are optional. Called with no arguments the tool returns a summary of all receipts in the current session.

### Example

**Agent prompt:**

> Query all high-risk actions from this session

**Tool response:**

```json
{
  "total_receipts": 12,
  "results": [
    { "action": "filesystem.file.delete", "risk": "high", "target": "delete_file", "status": "success", "sequence": 7 },
    { "action": "system.command.execute", "risk": "high", "target": "run_command",  "status": "success", "sequence": 3 }
  ]
}
```

:::tip
The agent can use `ar_query_receipts` to self-audit mid-session — for example, to confirm which files it has already written before deciding whether to proceed with a destructive operation.
:::

---

## `ar_verify_chain`

Verifies the cryptographic integrity of a receipt chain: checks every Ed25519 signature and every SHA-256 hash link between receipts.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `chain_id` | string | The chain to verify. Defaults to the current session's chain if omitted. |

### Example — valid chain

**Agent prompt:**

> Verify the audit trail for this session

**Tool response:**

```
Chain "chain_openclaw_main_sid-42" is valid: 12 receipts, all signatures and hash links verified.
```

### Example — broken chain

If a receipt has been modified or removed after it was signed, the tool reports the first position where verification fails:

```
Chain "chain_openclaw_main_sid-42": BROKEN at position 7
Tamper detected! The following receipts have issues:
  [7] urn:receipt:...: invalid signature, hash link
```

:::caution[A broken chain means receipts at or after the reported position cannot be trusted]
A valid chain guarantees that no receipt was altered, inserted, or deleted after signing. The strength of that guarantee depends on where the signing key lives: in the default in-process configuration the key is stored on disk alongside the agent, so a compromised agent process could read the key and forge receipts. With `daemonForwarding: true` the key lives in `agent-receipts-daemon` — the agent process cannot read the key material or rewrite already-signed receipts. Note that the daemon listens on a local Unix socket: any process running as the same OS user can still connect and emit new events; preventing that requires the daemon to run as a dedicated OS user (the production deployment). If the chain is broken, treat all receipts from the reported position onward as potentially compromised and investigate before relying on them.
:::

---

## Tool visibility

Both tools require explicit opt-in. The default `"coding"` profile in OpenClaw does not expose plugin-registered tools. Add them to `alsoAllow` in your `openclaw.json`:

```jsonc
{
  "tools": {
    "profile": "coding",
    "alsoAllow": ["ar_query_receipts", "ar_verify_chain"]
  }
}
```

See [Installation: Tool visibility](/openclaw/installation/#tool-visibility) for alternative configurations, including profile-level and plugin-level allowlisting.
