Quick answer
To debug a Cloudflare Agents tool call, use three layers in order:
- session replay for the recorded instructions, message, tool choice, arguments, result, and response;
- the agent trace for model, tool, approval, retry, subagent, token, and timing context;
- the full Workers trace for fetch, D1, KV, Durable Object, service-binding, and SDK spans.
Then reproduce the confirmed failure in a bounded test. A trace explains execution; it does not establish the correct answer by itself.
Tool-call triage
| Symptom | First check | Next check |
|---|---|---|
| Wrong tool selected | Instructions and available context in replay | Routing prompt and regression case |
| Malformed argument | Recorded tool arguments | Schema validation and argument construction |
| Tool timed out | Tool span duration and status | Child fetch or binding spans |
| Duplicate side effect | Retry pattern and tool calls | Idempotency key and source-system log |
| Approval bypassed | Approval event and scope | Enforcement point and destructive-action test |
| Stale result | Recorded result and timestamps | Source freshness and cache behavior |
| Subagent drift | Parent/child trace nesting | Delegated instructions and returned artifact |
Debugging sequence
- Record the affected agent, conversation, turn, deployment, and trace identifiers.
- Confirm whether message and tool payloads were captured.
- Compare the selected tool with the user’s authorized intent.
- Validate arguments, scope, destination, timeout, and retry count.
- Follow the tool span into the relevant Worker infrastructure spans.
- Reconcile the tool result with the source system.
- Check whether the final response preserved uncertainty and failure state.
- Add a test covering selection, arguments, idempotency, approval, and response handling.
For data-capture boundaries, use the session replay privacy guide. For the two trace layers, use Agents vs Workers observability.
Frequently asked questions
Where should I start?
Use replay for context, the agent trace for behavior, and the Workers trace for infrastructure.
Can HTTP 200 still be an agent failure?
Yes. Tool selection, stale context, retries, or the final answer can be wrong despite a successful request.
Should I capture every payload?
No. Use payload recording only when its debugging value is compatible with the data, access, and retention policy.
Official sources
Source check: August 6, 2026. Verify current capture controls, supported spans, and access boundaries for the selected harness.