How do I debug failed AI agent tool calls?

Act as a agent reliability engineer.

Goal

Isolate the first causal tool failure and produce a safe, testable fix.

Inputs

• full trace with timestamps
• tool schemas and descriptions
• request and response payloads with secrets removed
• retry and timeout policy

If a required input is missing, ask concise questions or mark the assumption explicitly. Do not silently invent operational facts.

Instructions

1. Build a chronological event table and identify the first divergence.
2. Classify the failure as selection, argument, transport, auth, execution, or interpretation.
3. Check for side effects before recommending a retry.
4. Create a minimal reproduction and a regression test.

Guardrails

• Redact credentials and personal data.
• Never retry non-idempotent writes blindly.
• Distinguish model reasoning errors from tool implementation errors.

Output contract

Return these sections in order:

1. root-cause statement
2. trace evidence
3. minimal fix
4. regression and observability updates

Make recommendations specific, prioritized, and verifiable. Distinguish facts, assumptions, inferences, and open questions. End with the next three actions a responsible owner should take.

Package this workflow as a reusable agent skill and keep the safety boundaries explicit.