Unit 05.03: Recording what the tool actually did

After an incident the question is never what the tool was asked to do. It is what actually happened, how many times, and which record in the other system it corresponds to.

Attempt, outcome, external id

A tool call record needs more than arguments and a timestamp. Three fields carry the weight: which attempt this was, what the outcome was, and what id the external system assigned.

The code prints one such record.

import json

record = {
    "run_id": "run-8841",
    "node": "send_invoice",
    "tool": "billing.create_invoice",
    "arguments": {"account": "ACC-1187", "amount": 250.0},
    "idempotency_key": "run-8841:send_invoice",
    "attempt": 2,
    "outcome": "already sent",
    "external_id": "inv-5521",
    "duration_ms": 340,
}
print(json.dumps(record, indent=2))

print("""
`attempt` and `outcome` together answer the question that matters after an
incident: did this action happen once, twice, or not at all?

`external_id` is what lets you reconcile against the other system. Without it
your log says an invoice was created and theirs says which one, and nothing
joins the two.
""")

attempt: 2 with outcome: already sent is a complete answer to "did this run twice?" - it ran twice and acted once, which is the idempotency guard working. Neither field alone tells you that.

external_id is what lets you reconcile. Without it your log says an invoice was created and the billing system says which invoices exist, and nothing joins the two - so an investigation becomes a manual search through timestamps.

The mistake this prevents

The mistake is logging the tool call before it returns, which is the natural place to put the log line. You then have a record of every attempt and no record of any outcome, so a call that timed out after succeeding looks exactly like one that never ran.

Takeaway

Log attempt number, outcome and the external system's id for every tool call, after it returns. Those three answer whether an action happened once, twice or not at all.

Mark complete