AI GUIDEA request is not a result
A fictional library assistant is asked: “Can I collect my reserved book today?” It needs the current reservation, not a plausible answer about library opening hours. A tool is a function the application exposes to obtain that information. The model can request it; the application controls execution.
For client tools, keep three events separate: Claude requests an operation, your code executes it, and Claude explains the returned evidence. This separation makes failures understandable. A polished explanation with no successful lookup does not answer the question.
Prerequisite: CA01 and basic familiarity with JSON, a text format for named fields and values. The exercise below traces an invented interaction on paper. It does not require API access.
Trace the cycle
Define a read-only operation, get_reservation(reservation_id). Assume the application has already verified the user's right to see reservation R17. It sends the user's question and the tool definition to Claude.
Illustrative assistant content: tool_use with id “call-1”, name “get_reservation”, input {"reservation_id":"R17"}. The application checks the name and arguments, performs the lookup and records the result. It then returns a tool_result referencing “call-1”, for example {"status":"ready","collection_deadline":"2026-11-14","branch":"North"}.
The follow-up request includes the original conversation, the assistant's tool request and the matching tool result. Claude can now explain that the reservation is ready at North branch. It still cannot establish today's opening hours unless those were supplied or checked separately. The identifiers matter: a result must be connected to the operation that produced it.
Handle other outcomes
Inspect stop_reason rather than searching the assistant's prose for “done”. A client tool request is signalled by tool_use. end_turn ends the response; it is not proof that the user's real-world task succeeded. max_tokens indicates an output limit, not a complete result. Other stop reasons need explicit handling according to the current API reference.
If the lookup returns “not found”, the assistant should report that outcome, not invent a reservation. If it times out, a limited retry may be appropriate. If access is denied, retrying with a different customer identifier is not recovery.
For multiple requested tools, keep each result linked to its own request. Only parallelise independent operations. A request to confirm collection depends on knowing which reservation is ready; it cannot safely race ahead of that lookup.
Your trace and answer key
Draw six boxes: user request, model tool request, permission check, tool execution, matching result, final explanation. Add a timeout branch and a not-found branch. Write the exact evidence needed before saying “ready for collection”.
Now inject a tool result that says the book is ready but omits the branch. A sound response states what is known and asks or checks where to collect it. It does not guess the nearest branch. Inject an interrupted model response: your system must mark the run incomplete rather than save a partial answer as approved.
You have understood the cycle if every factual claim has a supplied fact or successful result behind it, denied operations cannot execute, and interruption remains visible. Next: CA03 explains how to make tool boundaries understandable to both the model and the application.
Sources
Read the original sources to explore the topic and check specific claims.