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

# Audit Trail (Memo + Decision Context)

> Attach a human-readable reason and structured decision metadata to every paid tool call. Both land on the receipt for debugging, oversight, and supervisor agents.

Every paid tool call accepts two optional audit fields:

| Field             | Type                  | Purpose                                                                                                                                                              |
| ----------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `memo`            | string (≤ 1000 chars) | Human-readable reason this tool was called. Shows up on the receipt — useful when you're triaging spend or debugging an agent that went off the rails.               |
| `decisionContext` | object                | Machine-readable companion. Open schema with known fields (`goal`, `goalId`, `alternatives`, `confidence`) plus any extras. Consumed by supervisor / auditor agents. |

The SDK warns (does not error) when a paid tool is called without `memo`. Both fields are stored on the receipt — see [`GET /v1/analytics/receipts`](/api-reference/analytics/receipts).

## TypeScript SDK

```typescript theme={null}
import { OneShot } from "@oneshot-agent/sdk";

const agent = await OneShot.create({ cdp: true });

await agent.email(
  { to: "lead@acme.com", subject: "Follow-up", body: "..." },
  {
    memo: "Following up on demo request from yesterday's webinar",
    decisionContext: {
      goal: "Convert webinar leads to discovery calls",
      goalId: "goal_01HX...",
      alternatives: ["sms_send", "voice_call"],
      confidence: 0.78,
      // Open schema — any extra keys are stored verbatim
      campaign: "webinar-q2",
    },
  },
);
```

`memo` is plain text. `decisionContext` is any JSON-serialisable object — known fields are typed (see `DecisionContext` in the SDK types), extras are kept as-is.

## Python SDK

```python theme={null}
from oneshot import OneShot

agent = OneShot.create(cdp=True)

await agent.email(
    {"to": "lead@acme.com", "subject": "Follow-up", "body": "..."},
    memo="Following up on demo request from yesterday's webinar",
    decision_context={
        "goal": "Convert webinar leads to discovery calls",
        "goalId": "goal_01HX...",
        "alternatives": ["sms_send", "voice_call"],
        "confidence": 0.78,
        "campaign": "webinar-q2",
    },
)
```

Python accepts both `decisionContext` and `decision_context` — the SDK normalises to camelCase before sending.

## Raw HTTP

If you're not using an SDK, just include `memo` and `decisionContext` in the JSON body of any paid tool call:

```bash theme={null}
curl -X POST https://win.oneshotagent.com/v1/tools/email/send \
  -H "Content-Type: application/json" \
  -H "X-Payment-Proof: ..." \
  -d '{
    "quote_id": "qte_01HX...",
    "from_address": "agent@oneshot.ai",
    "to_address": "lead@acme.com",
    "subject": "Follow-up",
    "body": "...",
    "memo": "Following up on demo request from yesterday'\''s webinar",
    "decisionContext": {
      "goal": "Convert webinar leads to discovery calls",
      "confidence": 0.78
    }
  }'
```

## Validation

The SDK does light client-side validation before sending:

* `memo` over 1000 chars → truncated with a warning log
* `memo` empty / non-string → dropped silently
* `decisionContext.confidence` outside `[0, 1]` → dropped silently
* `decisionContext` non-object → dropped silently

These guardrails keep malformed values from blocking the underlying tool call.

## Where it shows up

Both fields are written onto the receipt at creation time:

```json theme={null}
{
  "receipt_id": "rcpt_01HGW2HB4V4T0PZGJ8PFDRCHQM",
  "category": "communication",
  "subcategory": "email",
  "amount_usdc": "0.150000",
  "memo": "Following up on demo request from yesterday's webinar",
  "decisionContext": {
    "goal": "Convert webinar leads to discovery calls",
    "confidence": 0.78,
    "campaign": "webinar-q2"
  },
  "status": "settled",
  "created_at": "2026-05-11T14:30:00Z"
}
```

Query via [`GET /v1/analytics/receipts`](/api-reference/analytics/receipts). The fields are returned alongside every other receipt attribute — no extra request needed.

## When to use which

* **Memo only** — quick debugging. Set it on every paid call as a one-liner ("why am I calling this?"). The SDK nudges you with a warn log if you forget.
* **Memo + decisionContext** — agents under programmatic oversight (supervisor agents, audit pipelines, eval rigs). The structured context lets a downstream system reason about the decision without parsing prose.
* **Neither** — fine for fire-and-forget scripts where the receipts are noise. The SDK won't block you; you just lose the audit trail.

## Tag vs memo vs decisionContext

These three fields tell different stories about the same receipt:

| Field             | Set when                                                                                                            | Answers                              |
| ----------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| `memo`            | At call time                                                                                                        | *Why did I make this call?*          |
| `decisionContext` | At call time                                                                                                        | *What was the structured reasoning?* |
| `value_tag`       | After the outcome is known — via [PATCH `/v1/analytics/receipts/{receiptId}/value`](/api-reference/analytics/value) | *Did this call generate value?*      |

Together they form the input → outcome chain that powers [RoCS](/api-reference/analytics/rocs).