AI Agent Tool Use: Designing APIs That Models Can Call Reliably
We built an internal agent for a client that needed to query inventory, adjust orders, and issue refunds through their existing REST API. Our first attempt just exposed the existing endpoints as tools, documented the same way they were documented for human developers. The agent called the wrong endpoint or passed malformed parameters on roughly one in six attempts during testing — not because the model was weak, but because the API wasn't designed to be called by something without judgment about ambiguous cases.
The biggest fix was collapsing multi-step human workflows into single tool calls. The refund endpoint required first fetching the order, then checking eligibility, then calling a separate refund endpoint with a specific reason code — three calls a human developer handles fine by reading docs, but a place where the agent regularly skipped the eligibility check. We wrote a single `process_refund` tool that did all three internally and returned a clear success or a specific, actionable error.
We also rewrote error messages specifically for the model to consume. The original API returned generic messages like 'invalid request' with an HTTP 400. We changed tool-facing errors to say exactly what was wrong and what to try instead — 'order_id not found; did you mean to search by tracking_number instead?' — which let the agent self-correct within the same turn instead of retrying the same failing call or giving up.
Parameter design mattered more than we expected. Free-text parameters like 'reason' invited inconsistent values that downstream systems couldn't process reliably; switching to enums with a fixed, documented set of values cut malformed calls by more than half. We kept one free-text field for the customer-facing note, since that genuinely benefited from natural language, and validated everything else against a strict schema before it ever reached the underlying API.
After these changes, the failure rate on the same test suite dropped from about one in six to roughly one in forty, and most of the remaining failures were genuinely ambiguous cases we'd want a human to review anyway. The pattern that stuck with us: tool APIs for agents deserve their own design pass, not a thin wrapper around whatever interface already exists for people.
