Recipe Trace a Failed Tool Call

Recipe: Trace a Failed Tool Call

Use when: a tool error appears in an alert, event feed, or transcript.

Procedure

1. Capture session ID, agent ID, tool name, and failure timestamp.
2. Open the event immediately before the failure. It often contains the triggering request or permission decision.
3. Inspect the failed tool event and result. Redact secrets before sharing.
4. Read the following transcript entries to see whether the agent retried, changed approach, or recovered.
5. Check sibling/child agents for parallel work that may have changed the same files.
6. Verify the real external state: file, command result, API object, or git diff. A tool error can occur after a partial side effect.
7. Classify the cause:
   • invalid arguments or path;
   • permission/policy denial;
   • dependency or environment failure;
   • timeout/network problem;
   • conflicting concurrent work;
   • provider/tool defect.
8. Reproduce only with a narrow, non-destructive command.

Useful CLI sequence

npx ccam session <session-id>
npx ccam events --session <session-id> --limit 100
npx ccam transcript <session-id> --agent <agent-id>

Done when

The report identifies the exact tool call, prior context, observed side effects, recovery status, and smallest next action. “Tool failed” alone is not a root cause.