---
title: "Tools: Troubleshooting"
description: "Common tool-call failures and fixes for schema mismatch, retries, and side effects."
icon: "circle-exclamation"
mode: "wide"
---

## Common issues

- Schema mismatch: align tool args with declared model output schema.
- Repeated side effects: add idempotency keys.
- Tool timeouts: define retries with bounded backoff.