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

# Tool calls

> One attempt by the agent to use a patch. The unit of record for what an agent actually did.

Every time an agent uses a capability, a tool call is recorded — before it runs, not after. Tool calls appear nested inside turns in the [trace](/guides/traces).

## Fields

| Field | Meaning |
| - | - |
| `patch_ref` | Which patch, at which version — `send_payment@3`. |
| `interaction` | `silent`, `interactive`, `handoff`, or `proposed_action`. |
| `gate` | Set to `confirm` when the call was held for approval. |
| `status` | `pending`, `ok`, or `failed`. |
| `args` | What the agent decided to send. |
| `result` | What came back, after redaction. |
| `request` | The egress we actually made, for debugging. |
| `risk` | Base and effective risk levels. |
| `reliability` | Whether the call is idempotent, and its retry mode. |
| `duration_ms`, `cost_credits` | Timing and cost for this call. |

## Status tells you what happened

`pending` means the call was recorded but has not completed — either it is in flight, or it is being held at a gate waiting for a human.

`failed` covers three different situations, distinguished by the result:

* Your endpoint errored — `result` carries the error message.
* A held write was **rejected** — `result` is `{ "declined": true, … }`.
* A proposed action was reported as failed — see the attached outcome.

A failed tool call does not usually fail the run. The error is handed to the model, which gets a chance to explain or try something else.

## Args are the agent's decision

`args` is what the model chose to send, validated against the patch's input schema. When an agent does something surprising, the args are usually where the surprise is visible — before you look at your own endpoint.

## Redaction applies here

Fields a patch declares as redacted are stripped from `result` before it is stored and before the model sees it. What you read in a trace is the redacted form; the original is never persisted.


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