> ## 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.

# The Patch object

> A capability an agent can use. Authored in the dashboard; visible over the API as a reference and inside traces.

See [Patches](/guides/patches) for authoring and semantics.

## The reference

Patches are named `key@version`:

```
send_payment@3
ask_user@1
```

This is what appears as `patch_ref` on every [tool call](/api-reference/tool-call), and in `pending_confirmation` and `pending_action`.

The version is part of the identity. A wired patch names one exact version, so changing a patch does not alter agents that pinned an earlier one.

## Declaration

What an agent carries about a patch, visible in `agent_snapshot`:

<ResponseField name="key" type="string" required>
  Unique within the workspace. Seven keys are reserved by built-in primitives.
</ResponseField>

<ResponseField name="title" type="string" required>
  Shown to you, and to the model as the tool name.
</ResponseField>

<ResponseField name="description" type="string">
  How the model decides whether to use it. The single highest-leverage field.
</ResponseField>

<ResponseField name="binding" type="object" required>
  `customer_endpoint`, `api_product`, or `native_utility`. A customer endpoint carries method, route, egress auth, and optionally a pinned connection.
</ResponseField>

<ResponseField name="interaction" type="enum" required>
  `silent`, `interactive`, `handoff`, or `proposed_action`.
</ResponseField>

<ResponseField name="input" type="object" required>
  JSON schema for the arguments. Enforced before any call is made.
</ResponseField>

<ResponseField name="output" type="object">
  JSON schema for the result.
</ResponseField>

<ResponseField name="render" type="object">
  Optional. `{ "kind": "..." }`. When set, the patch's result is emitted as a [rich-message](/guides/messages#rich-messages) data block of this `kind` for you to render, instead of only reaching the model. Set it in the patch builder's **Render as** field.
</ResponseField>

<ResponseField name="risk" type="object" required>
  `base` is `low`, `medium`, `high`, or `critical`. An agent can raise it, never lower it.
</ResponseField>

<ResponseField name="reliability" type="object">
  `idempotent`, and a retry mode.
</ResponseField>

<ResponseField name="redact" type="array">
  Fields stripped from results before storage and before the model sees them.
</ResponseField>

<ResponseField name="price" type="object">
  Per-call price, for priced products.
</ResponseField>

## Permission is not on the patch

How an agent may use a patch — **Always allow**, **Always ask**, **Always deny** — belongs to the wiring, not the declaration. The same patch can be gated on one agent and free on another.

## Errors

| Code | Status | When |
| - | - | - |
| `unknown_patch` | `422` | The agent wires a patch that no longer resolves. |


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