Agent Tool Failure Recovery

Find the first broken contract

Walk the trace from user authority and intended outcome through tool exposure, selection, call identifier, schema validation, policy validation, handler execution, result matching, model continuation, and external postcondition. Distinguish wrong tool, missing tool, invalid arguments, rejected authorization, dependency failure, timeout, malformed result, unmatched result ID, injected tool content, loop exhaustion, and an outcome that is unknown after a write.

Never ask the model to decide whether it had authority or whether a side effect occurred. Enforce those checks in application code. Treat external tool results as untrusted data, preserve provider-specific call/result ordering, and do not substitute prose for a required structured error result.

Record and contain the failed transition

Pause the loop before another consequential action. Record stable operation, trace, call, and result identifiers; the redacted arguments; schema and policy versions; executor; timeout; attempt; result class; and observed external state. Use a controlled test client or MCP Inspector against an isolated target when protocol or server behavior needs reproduction.

User outcome and authority: [REQUEST -> ALLOWED SCOPE]
Trace/call/result IDs: [CORRELATION]
Tool and contract version: [NAME -> SCHEMA/POLICY]
Executor and target: [CLIENT | PROVIDER | MCP SERVER -> RESOURCE]
Failure stage: [SELECTION | VALIDATION | AUTH | EXECUTION | RESULT | CONTINUATION | POSTCONDITION]
Observed result: [SUCCESS | FAILURE | UNKNOWN]
Attempts and budgets: [TOOL/TIME/COST/LOOP]
External-state check: [POSTCONDITION OR RECONCILIATION RESULT]
Owner and cadence: [SERVICE OWNER -> UPDATE INTERVAL]
Stop criteria: [AUTH FAILURE | UNKNOWN WRITE | BUDGET | INJECTION | CONTRACT MISMATCH]
Recovery: [CORRECT RESULT | COMPENSATE | RESTORE | MANUAL QUEUE]
Verification: [ISOLATED REPRODUCTION + END-TO-END POSTCONDITION]

Expected evidence and verification

Expected evidence is a complete redacted transition from authorized request to tool contract, execution, result, continuation, and postcondition, plus the containment and owner. Verify the fix with deterministic schema and policy tests, provider-format fixtures, timeout and duplicate-delivery cases, injected-result cases, isolated execution, and a final end-to-end trajectory.

Stop the agent when authorization fails, a write outcome is unknown, result identity or ordering is broken, untrusted content crosses an instruction boundary, budgets are exhausted, or the observed state differs from the claimed state. Recovery means reconciling the target before retry, returning a typed error to the loop, applying an approved compensation or rollback, restoring the last verified tool contract, and routing unresolved operations to a human queue.