Tool Calling Is a Contract, and the Model Will Break It

Here is the sentence that causes most tool-calling bugs: "the model called the weather API." It did not. It cannot. A language model produces one thing, text, and it has no way to reach out and run your code.

What actually happens is smaller and stranger. You describe your tools to the model. When it decides it wants one, it writes text that names the tool and gives a JSON object of arguments. That text is a request, a note that says "please run get_weather with {"city": "Berlin"}." Your own code, the orchestrator from the previous lesson, reads that note, runs the real function, and writes the result back into the model's context. The model proposes. The orchestrator disposes.

That gap is the whole lesson. Because the model's request is just text it generated, it can be wrong. It can pass a string where you need a number. It can leave out a required field. It can name a tool that does not exist. It can pick a real tool that is the wrong one for the job. None of these are exotic. They happen in normal operation, from good models, on ordinary inputs. If your orchestrator runs whatever the model proposes without checking it, those broken proposals hit your real functions, and your database write, your payment call, your file delete, runs with garbage arguments.

So tool calling is a contract. The schema is the contract. The model is a party that will, some fraction of the time, break it. Your job is to be the party that checks the contract on every single call before anything real happens.

A few terms appear on almost every slide of this lesson. Here they are in plain English.

JSON is a plain text format for data. It writes values as text, for example {"city": "Berlin", "days": 3}. The part before each colon is a field name, and the part after it is the value. Notice that 3 without quotes is a number, and "3" with quotes is a piece of text, called a string. That small difference causes many real bugs.

The arguments of a tool call are the inputs the model wants to pass to the tool, written as a JSON object.

A schema is a written description of what valid arguments look like: which fields must be there, what type each one has, and which values are allowed. JSON Schema is a common standard format for writing such descriptions, and it is the format model providers accept when you describe a tool.

A type is the kind of a value: a whole number (an integer), a decimal number, a string, true or false (a boolean), a list or an object.

An enum is a field that may only take one value from a fixed list, for example "public" or "private".

To validate means to check the arguments against the schema and collect every rule they break, before anything runs.

An observation is what the orchestrator writes back into the model's context after a call: the tool's result if it ran, or an error message if it did not. The model reads the observation on its next turn.