Tool Calling / Function Calling

This is the mechanics post, and the cover signals depth: we're opening the round-trip and looking at exactly what happens under the hood. Posts 1 and 2 stayed at 'the model asks your code to run a function.' Now we make that precise enough to implement.

The goal is that by the end the reader understands the full request-to-answer cycle, how schemas drive the model's tool choice, why a single human question often costs two model calls, how tool_call_id matches results to their calls, and how parallel and chained calls work. This is the machinery most tutorials gloss over.

The steps slide lays out the round-trip as a recipe so the reader has the skeleton before the details. Send the prompt plus the tool schemas. The model returns a tool_call — a name and an arguments JSON. Your code parses and runs the real function. You send the result back as a special 'tool' message. The model reads that result and writes the final answer.

The crucial realization is that the model never executes anything itself; it only decides and then, later, summarizes. Execution always happens in your runtime between the two model turns. That separation is where both capability and control live, and every following slide elaborates one piece of it.

The cycle diagram visualizes the round-trip as the loop it actually is: ask, decide, execute, return, answer. Drawing it as a cycle rather than a straight line foreshadows that this same pattern, repeated, is exactly what an agent does. For a single tool call you go around once; for an agent you go around many times.

The 'Return' node is the one beginners most often forget — the result has to flow back into the conversation, or the model never gets to use it. Making it a distinct step in the cycle keeps it from being skipped, which is fitting since forgetting it is one of the mistakes in post 5.

This slide explains how the model actually chooses a tool, which newcomers often imagine as something mysterious. Each tool is described by a name, a one-line purpose, and a JSON Schema for its arguments. The model sees only this description — never your source code. It pattern-matches the user's prompt against these descriptions to decide which tool fits and how to fill in the arguments.

The consequence is that your schema is the model's entire understanding of the tool. A clear, well-typed description leads to correct calls; a vague one leads to wrong tools and malformed arguments. This is why post 5 treats tool descriptions as a form of prompt engineering rather than mere documentation.

This code slide shows a real tool schema so the abstract 'name, purpose, and argument schema' becomes concrete. The example describes get_stock_price: a name, a human-readable description, and a parameters object declaring a 'ticker' string with its own description and marking it required. This is the exact JSON shape the API expects.

Notice that even the individual parameter carries a description ('e.g. AAPL'). Those inline hints measurably improve how reliably the model fills arguments. The whole schema is essentially a contract written for the model to read, which is why getting it right is so much of what makes tool calling work in practice.

This slide explains why one human question typically costs two model calls — a point that surprises people and matters for both latency and cost. On the first call, the model sees the question and the available tools, decides it needs data it doesn't have, and returns a tool_call instead of an answer. You then run the function. On the second call, you send the result back, and the model — now holding real data — writes the final answer.

Understanding this two-trip structure explains why tool-using interactions are slower and more expensive than a single completion: every tool call adds at least one more round-trip to the model. For an agent that calls several tools, that multiplies.

The pipeline diagram makes the two-trip structure visual: trip one is the model deciding and emitting the call, the middle stage is your function running, and trip two is the model turning the result into an answer. Placing the function run between the two model trips emphasizes that your code is the meat in the sandwich — the model bookends it but your runtime does the real work.

This framing also clarifies where you have control. Everything between the two trips happens in your code, which is exactly where you validate arguments, enforce permissions, and decide whether the call should even run.

This slide explains tool_call_id, the small detail that makes everything robust. Each tool call the model emits carries a unique id. When you send the result back, you echo that same id on the 'tool' message. That linkage lets the model match each result to the exact call it made.

The id becomes essential the moment the model emits several tool calls at once, because the results may come back in any order. Without the id, the model couldn't tell which result answers which call. It's a tiny mechanism, but it's what allows parallel tool calling to work correctly, and forgetting to echo it is a common source of malformed-conversation errors.

This code slide shows the message thread building up across a tool call, which is the clearest way to see how the pieces connect. The user message asks for AAPL's price. The model's turn one is an assistant message containing a tool_calls array with an id and the function name and arguments. You run the function, then append a 'tool' message carrying the same id and the result.

The arguments arrive as a JSON string, which is why your code has to parse them — a detail the next post handles explicitly. Seeing the literal message list demystifies the whole thing: a tool call is just a structured exchange of messages with roles, where the id stitches each result to its call.

This slide covers parallel and chained calls, the two ways tool calling scales beyond a single function. Parallel: in one turn the model can emit several tool calls at once — say, fetching two stock prices to compare. You run them all and append one tool message per id. Chained: the result of one call informs the next, like searching for an order id and then looking up that order.

The key insight is the final bullet: looping this pattern — decide, call, observe, repeat — is exactly what an agent is. Tool calling is the single step; an agent is that step run in a loop until the goal is met. This connects the mechanics directly back to the agents material from earlier in the series.

The flow diagram traces a parallel-call example end to end: a question that compares AAPL and MSFT produces two tool calls, one per ticker, which return two results matched back by id, after which the model compares them and answers. It makes the abstract 'parallel calls' concept tangible with a concrete, relatable task.

Seeing two calls fan out and two results come back, each tied to its call, reinforces why the id mechanism matters. It also shows that parallelism is a model decision — the model chose to issue both calls in one turn because the task naturally needed both, not because you orchestrated it.

The CTA points from theory to practice. We've covered the full round-trip, how schemas drive the model's choice, why it takes two model calls, how tool_call_id matches results to calls, and how parallel and chained calls work.

Day 78's teaser promises a real, runnable build. Post 4 assembles everything here into working code you can paste into a file — defining a real function, describing it with a schema, sending the request, reading and executing the tool call, returning the result by id, and getting the grounded final answer, then showing the same flow in the Anthropic SDK.