The Tool Invocation Lifecycle
A tool call is not one event. It is a fixed sequence of checkpoints, and exactly where a call stops tells you which of two error channels applies and what a caller should do next. Walk a tool invocation through every checkpoint: discover, list, select, confirm, call, validate, execute, and result. Tell which checkpoints exist only inside the host application versus which ones actually put a message on the wire. Explain why an unknown tool is always a protocol error and why a bad argument is almost always a tool execution error instead. Apply the retry rule for both an inputrequired result and a broken stream: a fresh JSON-RPC id every time, never the one that already failed. Reason about idempotentHint as an untrusted hint, not a guarantee, when deciding whether a blind reissue is safe. Distinguish a hard timeout that makes the client give up from an inputrequired result that only pauses the call. Picture an agent asking a server to poll a build, publish a release, or look something up. In the easy story, a tool call is a single event: you send it, you get an answer, done. Real calls do not work that way. Between the moment a model decides to use a tool and the moment the caller has something final to act on, the…
The Tool Invocation Lifecycle: A tool call is not one event. It is a fixed sequence of checkpoints, and exactly where a call stops tells you which of two…
This free lesson is part of the AI Engineering from Scratch curriculum. Read the full explanation, run the lesson code, and verify the result in the interactive reader or from the repository source.
Browse the complete course catalog or open this lesson on GitHub.