Lesson 11 — Tool calling with a real API (shape)

The tool call inside a real response

In Lessons 7–9 the model asked for a tool with our own JSON. Real APIs have a fixed shape for this. In Anthropic's Messages API you send your tool schemas in a tools list (with name, description and input_schema). When the model wants a tool, the response has "stop_reason": "tool_use" and its content list holds a tool_use block:

{"type": "tool_use", "id": "toolu_01", "name": "get_weather", "input": {"city": "Almaty"}}

The content list can also hold text blocks, so you loop over the blocks and pick the one with type == "tool_use". Your code runs the tool, then sends the result back as a tool_result block inside a "user" message. Its tool_use_id must equal the id of the call, so the model knows which call the result answers:

{"role": "user", "content": [{"type": "tool_result", "tool_use_id": "toolu_01", "content": "sunny, 12 C"}]}

OpenAI's Responses API uses the same idea with other names: a function_call item with call_id, name and arguments, and you answer with a function_call_output item. Watch out: there arguments is a JSON string, so you need json.loads first.

Why it matters: this is the dispatcher from Lesson 9, plugged into a real response shape. The dict below mimics that shape, so it runs offline.