Updated
Make agent tool calls reliable with precise contracts, server-side authorization, idempotent writes, useful errors and tests for ambiguous outcomes.
Reliable tool calling requires more than valid JSON: the agent must select the right operation, the application must validate authority and business rules, and retries must not repeat side effects. Treat the model's call as a proposed action. Your service remains responsible for deciding whether that action can execute and for confirming its result.
A scheduling assistant illustrates the problem. It receives “Move my appointment to Friday afternoon” and produces a valid request for a specific slot. That request may still refer to the wrong Friday, another customer's appointment or a slot that became unavailable seconds earlier. Structured output addresses shape; it does not resolve those business facts.
Distinguish selection, argument and execution failures
Record failures by stage so the remedy matches the problem. If an agent calls cancellation instead of rescheduling, improve the operation boundary and evaluation cases. If it sends an unsupported date format, tighten the schema. If the correct rescheduling call times out after a write, investigate execution and reconciliation.
Avoid treating every failure as “the prompt needs improvement.” A model cannot make an unavailable booking API reliable by reasoning harder. Nor should a server accept an unauthorized appointment merely because the tool description told the model to be careful.
Test these stages independently, then run complete user journeys. A regression can pass schema tests while breaking the user's intent.
Give each operation an unambiguous contract
Use names and descriptions that distinguish nearby actions. Explain whether rescheduling preserves the existing booking identifier, whether it sends a notification and what happens when no slot is available. Include the response's limits, such as pagination or time range.
Prefer constrained fields where the domain is known. Require a time zone for local appointment times. Use stable record identifiers after lookup, rather than allowing a write operation to guess which “Ali” or “Sarah” the user means.
The OpenAI function calling guide documents strict schema mode and its supported constraints. Enable a compatible strict schema explicitly when your integration supports it, and still validate on the server. Schema conformance cannot prove that a record belongs to the authenticated customer.
A useful contract review asks:
Can a reader distinguish this operation from similar tools?
Are required units, currencies and time zones explicit?
Can the server derive identity instead of trusting a supplied user identifier?
Are optional values represented consistently?
Does the result distinguish completed work from accepted work?
Is truncation or pagination visible?
Are error categories machine-readable?
Does the contract disclose external side effects?
Enforce permissions at the action boundary
Resolve the caller's identity from the authenticated session or token. Check access to the appointment and authority to change it at execution time. Do not let the model choose the tenant context through a free-form argument.
Apply business rules after structural validation. The proposed slot must exist, the service must permit rescheduling and any deadline must still be satisfied. If approval is required, bind it to the actual appointment and proposed time, then invalidate it if those inputs change.
Read-only tools need access checks too. A lookup that leaks another customer's availability or contact details can fail before any write happens. Tool outputs should contain only the fields needed for the next decision.
Separate a retry from a new action
Suppose the booking service changes the appointment but the response never reaches the agent. Retrying with a new action identifier could send two notifications or reserve another slot. The application needs a stable identifier for the intended reschedule across transport retries.
Persist that identifier before executing the write. Store the outcome so a repeated request can reconcile or return the existing result. Check that the same identifier cannot be reused with different action parameters.
Stripe's idempotent request documentation provides a concrete API example of idempotency keys and replay behavior. Other services may implement different retention periods and error semantics; read the actual destination's contract rather than assuming all APIs behave alike.
An operation without native idempotency may need a local operation record and a destination lookup before retry. If you cannot determine whether a write happened, mark the outcome unknown and route it for reconciliation. A confident “failed” message is dangerous when the booking may already have changed.
Retry only recoverable conditions
Classify temporary transport errors and rate limits separately from invalid input, permission denials and business rejection. Use bounded backoff where retry is appropriate. Respect provider retry guidance and the user's overall deadline.
A “slot no longer available” response calls for a new choice, not twenty attempts at the same slot. An expired authorization needs a legitimate authorization flow; adding explanatory text to the prompt does not renew it.
Return useful errors without exposing secrets or internal stack traces. Give the agent a code such as slot_unavailable and the next permitted step. Do not include arbitrary instructions from a downstream system as trusted commands.
Control parallel calls and ordering
Two independent availability lookups may run together. Reserving a replacement and cancelling the original require an explicit ordering and rollback policy. Otherwise, one failure can leave the customer with no booking or two bookings.
Keep related writes in a service-level transaction when possible. When they span systems, record each completed step and define compensation or manual recovery. The model should not be the only place where that sequence exists.
Our multi-agent architecture guide discusses coordination boundaries. Splitting the two actions across agents does not remove their dependency.
Evaluate behavior under realistic failure
Build a small test set around actual scheduling ambiguity: a missing time zone, two appointments with the same customer, a daylight-saving transition, a revoked session and a slot taken between lookup and write.
Then inject a timeout immediately after a successful write. Verify that the system reconciles the original action, avoids duplicate notification and tells the user the confirmed appointment time. Track final state, not only whether the model chose the expected function name.
Use agent action acceptance testing for the release gate and monitoring traces to diagnose production outcomes.
Do fewer tools always improve accuracy?
No universal count guarantees accuracy. Overlapping descriptions can confuse selection, while an oversized all-purpose tool can hide unsafe choices. Compare alternative tool sets on your own task examples and failure cases.
Can strict output remove the need for human review?
No. Strict output addresses the contract's structure. The need for review depends on authority, consequence and the evidence available for the particular action.
Written by
Moueen Togarvi
Founder & CEO at Voquarn Code, focused on product engineering, search growth, and practical AI systems.
