A tool response should tell the assistant what happened and what it may do next. Free-form success messages force the model to infer whether a request was saved, queued, rejected, or only checked.
Reliable responses expose state explicitly
A reliable tool-response contract separates execution outcome, domain result, safe explanation, and recovery options. Use stable status values and authoritative references. Keep diagnostic identifiers separate from private internal errors.
In a proposed write response, completed means the defined commitment occurred. Pending means execution is not finished. Rejected means the operation did not satisfy a stated condition. Unknown means the service cannot yet establish whether the effect occurred. Document these meanings and test them across agent releases.
Avoid returning large raw records when the agent needs only an appointment reference and confirmed time. Smaller responses reduce accidental disclosure and make consequential fields easier to identify. They also require careful design so the agent retains enough information to answer accurately.
Compare fictional response designs
One service returns “OK: processed appointment request.” That phrase could mean a queue accepted the request or an appointment was created. A clearer response states that the appointment is pending, supplies an operation reference, and permits a status check.
When the operation completes, the next response includes the authoritative appointment reference and confirmed details. The assistant can then change its wording from “submitted” to “confirmed.” The response should not ask the model to invent the missing distinction.
| Response condition | Contract requirement |
|---|---|
| Empty lookup result | Explicit empty result, not a transport failure |
| Validation failure | Safe field-level correction information |
| Pending operation | Stable reference and allowed follow-up |
| Completed write | Authoritative result reference |
| Unknown execution | Reconciliation instruction, no success claim |
Test unknown status values and missing fields. An older agent should fail safely when it cannot interpret a response rather than treat every non-error object as success.
Recovery instructions must remain bounded
A response may suggest a safe next step, such as asking for a missing date. It must not grant itself new permissions or override the application’s execution policy. Keep recovery guidance within the same trusted contract and access scope.
Version both structure and meaning. Changing a status from “queued for review” to “approved” is a semantic change even if the JSON shape remains identical. Include representative response fixtures in compatibility checks.
This contract is proposed. The voice integration case study describes related tool work. Review tool-error handling for the caller-facing consequence of each status.
Tool response FAQ
Is a human-readable message enough?
It can help, but stable structured outcomes are easier to interpret and validate consistently.
Should raw exceptions reach the assistant?
Return safe categories and diagnostic references instead of sensitive stack traces or database details.
Can every successful HTTP response mean business completion?
No. Transport-level success may only acknowledge a request; the domain contract must state what actually completed.