CORE GUIDE
Validate tool results before using them
A successful tool call only means a response arrived; the runtime still has to validate its shape, semantics and relationship to the intended action.
Mental model
Tool output crosses a trust boundary. Treat it like external input: parse it, validate the contract, classify ambiguity and only then let the result update workflow state or authorize another side effect.
Why it matters
APIs return partial success, stale data, unexpected enums, empty fields and transport-level success codes that hide business failure. If an agent feeds every response straight back to the model, malformed or misleading tool data can become authoritative context. Validation keeps the runtime in control and makes recovery decisions explicit.
01
Validate structure, semantics and postconditions
Check that the response matches the expected schema and version, then validate domain constraints such as identifiers, status combinations and required evidence. For side-effecting tools, distinguish request acceptance from confirmed completion and reconcile ambiguous states when needed. Convert raw responses into a smaller trusted observation before the agent sees them.
02
Example: payment API returns HTTP 200
A payment tool returns HTTP 200 with a JSON object whose business status is `pending_review`. Treating the call as successful would let the agent tell the user payment completed. A validator maps the response to a typed PENDING state and prevents fulfillment until a later authoritative status confirms completion.
Common failure modes
- Treating transport success as business success.
- Passing unvalidated third-party response text directly into authoritative agent state.
- Silently coercing unknown fields or status values into familiar ones.
Engineering heuristics
- Define a typed result contract for every tool the agent can call.
- Model UNKNOWN and PENDING explicitly when completion cannot be established.
- Keep raw tool evidence available for debugging while exposing a validated observation to the model.
Takeaways
- 01Tool responses are evidence, not automatically trusted state.
- 02Validation should happen at the runtime boundary.
- 03Explicit ambiguous states prevent confident but unsafe follow-up actions.
Related concepts from the Knowledge Graph
These relationships come from the canonical graph, not a separate Guide taxonomy.