AI engineering / Beginner / 01.12
Function Calling
How a model asks your code to do things it cannot do itself: look up facts, run sums, send requests. You stay in charge of every step.
13 min readFree
A model that can ask for help
The last lesson, Structured Output, ended with a promise: next, function calling, letting a model ask your code to do things. Here it is.
A model only writes text. It cannot look at today's weather, read your database, or send an email. Function calling is the trick that fixes this. You tell the model what helpers exist. When it needs one, it writes a short request. Your code does the work and hands the answer back.
Think of a hotel guest at the front desk. The guest cannot walk into the kitchen, so they ask the clerk for a sandwich. The clerk places the order and brings it back. The model is the guest. Your code is the clerk.
By the end you will know the loop, how to describe a tool, and how to keep it safe. This lesson also covers Tools and Function Calling.
Key words
- Tool (or function)
- A piece of code you wrote that the model is allowed to ask for, like get_weather.
- Tool call
- The model's written request to use a tool, with the values to use.
- Argument
- One value handed to a tool, like city = Paris.
- JSON
- A plain-text way to write lists and labelled values, like {"city": "Paris"}. Almost every language can read it.
- JSON Schema
- A way to describe what a JSON value must look like: which labels, what type each value is, which are needed.
- Validate
- Check that a value has the right shape before you use it.
- Allow-list
- A list of the only things permitted. Anything not on it is refused.
Why the model needs help
A model cannot see today's weather, your database or your inbox. It has only the words in the chat.
Tools fill those gaps. The OpenAI guide gives examples: get today's weather for a location, access account details for a given user ID, or issue refunds for a lost order. The first only reads. The last changes the world and costs money. We will come back to that.
Tip
The model never runs code. It only writes a request. Your program decides whether to run it. Everything safe about function calling comes from that one fact.
The Claude docs describe it the same way. They say that Claude "determines when to call a tool based on the user's request and the tool's description" and then returns a structured call that your application runs.
The loop, step by step
The OpenAI guide calls this a multi-step conversation between your application and a model, and lists five high-level steps. Here they are in plain words.
- 1
Send the question and the tool list
Your code sends the user's message plus a description of each tool the model may call.
- 2
Receive a tool call
The model answers with a request, such as "call get_weather with city Paris", instead of a final answer.
- 3
Run it yourself
Your code finds the tool, checks the request, and runs it. This is the only step where anything really happens.
- 4
Send the result back
Your code makes a second request to the model, now including what the tool returned.
- 5
Get the final answer
The model writes its reply in plain language. The guide notes that this can also be more tool calls, so the loop may go round more than once.
The Claude docs split tools into two kinds by where the code runs. Client tools run in your application. For these, Claude replies with a stop reason of tool_use, your code runs the operation, and you send back a tool_result. Server tools run on the vendor's own computers. This lesson is about the first kind.
Quick check
In function calling, who actually runs the tool?
Describing a tool
The model cannot see your code. All it knows about a tool is the description you write. So the description is the whole manual.
The OpenAI guide says a function definition has these fields: type (always function), name, description ("Details on when and how to use the function"), parameters, and strict. The parameters field is a JSON Schema that defines the input arguments.
A parameter is a slot for a value. The json-schema.org page on objects explains the pieces we need.
properties
Lists each slot by name, with a schema for what goes in it, such as a string or a number.
required
A list of slot names that must be present. By default, leaving properties out is valid, so you must say which are needed.
additionalProperties
By default extra slots are allowed. Setting it to false means no extras are allowed.
Below is a real function definition, copied from the OpenAI guide. Look at how it uses an enum, a fixed list of allowed values, for the units. It is shown without running it, because running it needs a paid account.
# From the OpenAI API docs (Function calling), shown without its output (not run here)
{
"type": "function",
"name": "get_weather",
"description": "Retrieves current weather for the given location.",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "City and country e.g. Bogotá, Colombia"
},
"units": {
"type": "string",
"enum": ["celsius", "fahrenheit"],
"description": "Units the temperature will be returned in."
}
},
"required": ["location", "units"],
"additionalProperties": false
},
"strict": true
}When the model decides to use it, the guide says the response holds an entry of type function_call with a call_id (used later to submit the function result), a name, and JSON-encoded arguments. In the sample, the arguments arrive as one string of text: "{\"location\":\"Paris, France\"}". That detail matters. Your code must turn that text into real values before use.
Other vendors use other labels. Claude's tool definitions use input_schema where OpenAI uses parameters. The idea is the same.
Run the loop yourself
Now let's build the whole loop in plain Python, free, with nothing to install.
The model here is a stand-in. The function fake_model follows a fixed script. If the question mentions Paris weather, it returns a tool call. If it sees a tool result, it returns a final answer. It is not a real model, so this code runs free. A real model is slower, costs money for every token, can give a different answer each run, and can fail or refuse. The weather and the exchange rate are also fixed, made-up values, so the numbers mean nothing.
The program has four questions. Watch what our code does with each one.
import json
# Two tools. Both are plain Python functions that we wrote.
WEATHER = {"paris": "18 C, cloudy", "tokyo": "24 C, sunny"}
MADE_UP_RATES = {("USD", "EUR"): 0.9, ("EUR", "USD"): 1.1} # invented numbers
def get_weather(city):
return WEATHER.get(city.lower(), "no data for that city")
def convert_currency(amount, from_code, to_code):
rate = MADE_UP_RATES[(from_code, to_code)]
return f"{amount * rate:.2f} {to_code}"
# What the model is told about each tool: a name, a description,
# and the arguments written as a JSON-Schema-style object.
TOOLS = {
"get_weather": {
"run": lambda a: get_weather(a["city"]),
"description": "Get today's weather for one city. Use it when the user asks about weather.",
"parameters": {
"type": "object",
"properties": {"city": {"type": "string", "description": "City name, e.g. Paris"}},
"required": ["city"],
"additionalProperties": False,
},
},
"convert_currency": {
"run": lambda a: convert_currency(a["amount"], a["from_code"], a["to_code"]),
"description": "Convert money between USD and EUR. Use it for money questions.",
"parameters": {
"type": "object",
"properties": {
"amount": {"type": "number", "description": "How much money"},
"from_code": {"type": "string", "enum": ["USD", "EUR"]},
"to_code": {"type": "string", "enum": ["USD", "EUR"]},
},
"required": ["amount", "from_code", "to_code"],
"additionalProperties": False,
},
},
}
PY_TYPES = {"string": str, "number": (int, float)}
def check_args(schema, args):
"""Return a problem as text, or None if the arguments look fine."""
for key in schema["required"]:
if key not in args:
return f"missing argument: {key}"
for key, value in args.items():
if key not in schema["properties"]:
return f"unexpected argument: {key}"
rule = schema["properties"][key]
if not isinstance(value, PY_TYPES[rule["type"]]):
return f"{key} must be a {rule['type']}"
if "enum" in rule and value not in rule["enum"]:
return f"{key} must be one of {rule['enum']}"
return None
def fake_model(messages):
"""A STAND-IN, not a real model. It follows a fixed script."""
last = messages[-1]
if last["role"] == "tool":
return {"text": "Here is what I found: " + last["content"]}
question = last["content"].lower()
if "weather in paris" in question:
return {"call": {"name": "get_weather", "arguments": '{"city": "Paris"}'}}
if "dollars" in question:
return {"call": {"name": "convert_currency",
"arguments": '{"amount": 20, "from_code": "USD", "to_code": "EUR"}'}}
if "delete" in question:
return {"call": {"name": "delete_files", "arguments": "{}"}}
if "weather" in question:
return {"call": {"name": "get_weather", "arguments": "{}"}}
return {"text": "I can help with weather and money."}
def ask(question):
print("USER:", question)
messages = [{"role": "user", "content": question}]
for _ in range(3): # a limit, so the loop can never run forever
reply = fake_model(messages)
if "text" in reply:
print("MODEL (final):", reply["text"])
return
name = reply["call"]["name"]
print("MODEL asks for:", name, reply["call"]["arguments"])
tool = TOOLS.get(name)
if tool is None:
result = f"error: no tool called {name}"
else:
problem = check_args(tool["parameters"], json.loads(reply["call"]["arguments"]))
result = f"error: {problem}" if problem else tool["run"](json.loads(reply["call"]["arguments"]))
print("OUR CODE returns:", result)
messages.append({"role": "tool", "content": result})
for q in ["What is the weather in Paris?", "Convert 20 dollars to euros.",
"Delete my files.", "What is the weather?"]:
ask(q)
print()Output
USER: What is the weather in Paris?
MODEL asks for: get_weather {"city": "Paris"}
OUR CODE returns: 18 C, cloudy
MODEL (final): Here is what I found: 18 C, cloudy
USER: Convert 20 dollars to euros.
MODEL asks for: convert_currency {"amount": 20, "from_code": "USD", "to_code": "EUR"}
OUR CODE returns: 18.00 EUR
MODEL (final): Here is what I found: 18.00 EUR
USER: Delete my files.
MODEL asks for: delete_files {}
OUR CODE returns: error: no tool called delete_files
MODEL (final): Here is what I found: error: no tool called delete_files
USER: What is the weather?
MODEL asks for: get_weather {}
OUR CODE returns: error: missing argument: city
MODEL (final): Here is what I found: error: missing argument: cityQuestion one is the happy path: the stand-in asks for get_weather with city Paris, our code looks it up, and "18 C, cloudy" goes back.
Question two uses the second tool. Twenty dollars at the made-up rate of 0.9 gives 18.00 EUR. The check made sure the amount was a number.
In question three the stand-in asked for delete_files, a tool we never wrote. The loop found no such name and refused. TOOLS is an allow-list: a name not on it can do nothing.
Question four shows validation. The call had no city, so check_args returned "error: missing argument: city". That error went back as the tool result, so a real model could read it and try again. (Our stand-in just repeats it.)
We capped the loop at three rounds so it can never run forever. A real chat also keeps the model's own tool call in its history; we left that out to keep the code short.
Quick check
In the run above, why was the call to delete_files refused?
Keeping it safe
A tool call is just text written by a model, which can be wrong. Treat every tool call like a form filled in by a stranger.
Validate the arguments
Check type, required slots, allowed values and extras before running anything, as check_args did.
Allow-list the tools
Only run names you registered. Refuse everything else, as the loop did with delete_files.
Ask a human for risky actions
Before anything that spends money, deletes data or messages other people, show the details and wait for a yes.
JSON Schema helps twice here: it is the manual you send the model, and the rulebook you can check the reply against. Our check_args is a tiny home-made version.
The OpenAI guide has a strict mode. It says setting strict to true will "ensure function calls reliably adhere to the function schema, instead of being best effort." It needs additionalProperties set to false for each object, and every field in properties marked as required. That helps, but it does not replace your own checks. Your code still decides whether the action is allowed.
The third habit is my advice, not the docs'. To the loop, a refund looks like a weather lookup, so you add the gate. Here is a tiny one, with a pretend person who always says no.
# Tools that change the world need a human "yes" first.
NEEDS_APPROVAL = {"send_refund", "delete_file"}
def human_says_yes(question):
print("ASK HUMAN:", question)
return False # stand-in for a person clicking "No"
def run_tool(name, args):
if name in NEEDS_APPROVAL and not human_says_yes(f"Allow {name} with {args}?"):
return "refused: the person said no"
return f"{name} ran"
print(run_tool("send_refund", {"order": 42, "amount": 10}))
print(run_tool("get_weather", {"city": "Paris"}))Output
ASK HUMAN: Allow send_refund with {'order': 42, 'amount': 10}?
refused: the person said no
get_weather ranThe refund never ran, because the stand-in human said no. The weather tool, which only reads, ran straight away.
Writing good tool descriptions
A model picks tools by reading your words. Vague words give wrong picks. The OpenAI guide has a short list of habits for defining functions. These are its main points, in plain words.
Be clear and detailed
Explicitly describe the purpose of the function and each parameter, its format, and what the output means.
Make invalid states impossible
Use enums and clear structure. The guide's example is toggle_light(on: bool, off: bool), which allows a call that says on and off together.
Pass the intern test
Could a new intern use the function using only what you gave the model? If not, add the answers they would ask for.
Two more points from the guide. First, do not make the model fill in arguments you already know. If your code already has an order id, leave it out of the parameters and pass it in yourself. Second, keep the tool list short. The guide softly suggests fewer than 20 functions available at the start of a turn, though it calls that just a suggestion.
There is a cost too. The guide says function definitions count against the model's context limit and are billed as input tokens. Long descriptions on many tools add up. The Tokens lesson and the Context Window lesson explain those two ideas.
Tip
Test your descriptions like a prompt. Ask ten different questions and see which tool gets picked. Wrong picks are a sign to reword. The Prompt Engineering lesson covers testing in the same way.
What a real model changes
Our stand-in always follows its script. A real model does not, and that changes how you build.
It can pick the wrong tool
Or skip one it should have used. Good descriptions lower the chance, not to zero.
It can send bad arguments
Wrong types, missing values, made-up ids. Always validate.
It can ask for several calls at once
The OpenAI guide says responses can include zero, one or multiple calls, so it is best practice to assume there are several. Loop over all of them.
Each round trip is another request, so tool-heavy answers are slower and cost more. Cap your loops and log every call.
Quick check
A model asks to run a tool that refunds money. What is the safest first move?
Recap
The model only asks
It writes a tool call as text. Your code runs the tool.
The loop has five steps
Send the tools, get a call, run it, send the result back, get the answer.
You stay in charge
Validate arguments, allow-list tools, and ask a human before risky actions.
Next: ReAct, a model that thinks, acts, and looks again.
Sources
Last updated on 16 November 2026
Learn with me
Every lesson is free. I add new ones as I learn. Have a question, or want help with your own work? Book a short call.