The Tools Primitive: Calling Actions and Reading Their Results
A tool call is a request like any other. What earns it its own lesson is everything the result can carry back: plain text, an image, audio, a link to a resource, or a resource embedded whole, each one tagged with hints about who it is for and how fresh it is. Read a tools/list page for its pagination and caching hints, and explain why the tool list a client receives must not depend on which connection asked for it. Call a tool and read a CallToolResult apart into its three fields: content, structuredContent, and isError. Identify each content block type a tool result can carry, text, image, audio, a resource link, and an embedded resource, and what its own annotations describe. Apply the default value of each tool annotation when a server leaves the annotations object out, and explain why those defaults lean cautious rather than permissive. Trace how a change to a server's tool list reaches a client that already opened a subscriptions/listen stream. A server can expose one tool or several hundred. If tools/list answered with the whole set every time, in one unpaginated block, and the response carried no promise about how long the answer stayed good, every model turn would either re-fetch the entire catalog for nothing or act on a copy that might already…
The Tools Primitive: Calling Actions and Reading Their Results: A tool call is a request like any other. What earns it its own lesson is everything the result…
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.