Skip to content

03 · Tool / Function Calling: The Model Chooses, Python Executes

In Lesson 2, we gave the model a contract:

{
"action": "look_up_account",
"reason": "I need account data."
}

That was useful because Python could understand the decision.

But nothing actually happened.

Today we cross the next boundary:

We give the model access to specific Python capabilities.

Not arbitrary Python.

Not your whole application.

Specific functions that you choose to expose.

And the most important principle in today’s lesson is:

The model does not execute your function. It asks your program to execute it.

That distinction is the foundation of safe tool use.


Imagine a support application that needs to look up an invoice.

Forget AI for a moment.

def get_invoice_status(invoice_id: int) -> dict:
invoices = {
4812: {
"status": "unpaid",
"amount": 250,
},
4813: {
"status": "paid",
"amount": 175,
},
}
return invoices.get(
invoice_id,
{"error": "invoice_not_found"},
)

Normal Python:

result = get_invoice_status(4812)
print(result)

Output:

{
"status": "unpaid",
"amount": 250,
}

Nothing agentic yet.

We have simply created a capability.


Suppose we ask:

response = client.responses.create(
model="gpt-5.5-2026-04-23",
input="""
Has invoice 4812 been paid?
"""
)

The model has no access to:

get_invoice_status()

just because that function exists in your Python file.

This is one of the key things to understand.

Your application has two separate worlds:

MODEL WORLD
"Has invoice 4812 been paid?"
PYTHON WORLD
def get_invoice_status(...)

Something has to connect them.

Function calling is that connection.


We create a tool definition.

tools = [
{
"type": "function",
"name": "get_invoice_status",
"description": "Look up the current status of an invoice.",
"parameters": {
"type": "object",
"properties": {
"invoice_id": {
"type": "integer",
"description": "The invoice ID to look up.",
}
},
"required": ["invoice_id"],
"additionalProperties": False,
},
"strict": True,
}
]

Read that carefully.

We have not passed the Python function itself.

We passed a description of a function.

Conceptually:

You have a capability called:
get_invoice_status
It requires:
invoice_id: integer
Use it when you need to know
whether an invoice is paid.

Current Responses API function tools are described with a function name, description, and JSON Schema parameters. When the model wants to use one, the response can contain a function_call item with the function name, arguments, and a call_id. OpenAI function-calling guidance


from openai import OpenAI
client = OpenAI()
INVOICE_INSTRUCTIONS = """
Help answer invoice questions.
Use the invoice tool when invoice data is needed.
"""
response = client.responses.create(
model="gpt-5.5-2026-04-23",
instructions=INVOICE_INSTRUCTIONS,
input="Has invoice 4812 been paid?",
tools=tools,
parallel_tool_calls=False,
)

For this introductory cycle, add parallel_tool_calls=False so a response requests at most one function. We are deliberately showing one request/result exchange; Lesson 4 handles repeated turns and multiple calls. The complete example below also handles a response with no function call.

Now the model receives something conceptually like:

USER:
Has invoice 4812 been paid?
AVAILABLE TOOL:
get_invoice_status(invoice_id: integer)

The model might reason:

I cannot answer this from my existing context.
I need current invoice data.
I should request:
get_invoice_status(invoice_id=4812)

And this is where function calling becomes interesting.


You might expect:

Invoice 4812 is unpaid.

But the model doesn’t know that yet.

Instead, it may return a tool-call item conceptually like:

{
"type": "function_call",
"name": "get_invoice_status",
"arguments": '{"invoice_id":4812}',
"call_id": "call_abc123",
}

Notice what happened.

The model produced:

PLEASE CALL:
get_invoice_status(4812)

It did not execute:

get_invoice_status(4812)

Current API responses represent function arguments as JSON and attach a call_id so your program can later associate the tool result with the correct request. OpenAI function-calling guidance


The walkthrough below follows the branch where a completed response contains one function call. In that branch, tool_call exists before we read its fields. The complete example checks the other branches too.

Let’s inspect the response:

for item in response.output:
print(item.type)

You may see:

function_call

Now we find the function call.

tool_call = None
for item in response.output:
if item.type == "function_call":
tool_call = item
break

Then:

print(tool_call.name)

might give:

get_invoice_status

And:

print(tool_call.arguments)

might give:

{"invoice_id":4812}

Important:

tool_call.arguments

is JSON text.

So we parse it.

import json
arguments = json.loads(tool_call.arguments)

Now:

arguments

is:

{
"invoice_id": 4812
}

Now our program decides whether to run anything.

Even a strict tool schema does not replace the runtime execution boundary:

if (
not isinstance(arguments, dict)
or set(arguments) != {"invoice_id"}
or type(arguments["invoice_id"]) is not int
):
raise ValueError("Invalid invoice lookup arguments")

The check rejects missing or extra fields, non-object JSON, and values such as a string or boolean used as an invoice ID. A valid ID can still refer to a nonexistent or unauthorized record. Our fixture lookup is fictional and read-only; real account permissions remain application policy.

For the simplest example:

if tool_call.name == "get_invoice_status":
result = get_invoice_status(
invoice_id=arguments["invoice_id"]
)

And now, for the first time, the real function executes.

MODEL:
Please call get_invoice_status(4812)
PYTHON:
Okay, that is an allowed tool.
PYTHON:
get_invoice_status(4812)
DATABASE / APPLICATION:
unpaid

That division of responsibility is everything.


8. Never let the model execute arbitrary function names

Section titled “8. Never let the model execute arbitrary function names”

You might be tempted to do something like:

globals()[tool_call.name](**arguments)

Don’t.

That effectively says:

Model, tell me the name of some Python object and I’ll try to execute it.

Instead, create an explicit allowlist.

AVAILABLE_TOOLS = {
"get_invoice_status": get_invoice_status,
}

Then:

function = AVAILABLE_TOOLS.get(tool_call.name)
if function is None:
raise ValueError("Unknown tool")

And only then:

result = function(**arguments)

Now the boundary is obvious:

MODEL MAY REQUEST:
get_invoice_status
MODEL MAY NOT REQUEST:
delete_database
run_shell_command
read_secret_file
whatever_function_exists_in_python

Your program controls capability.

This is one of the most important security ideas in agent engineering.


At this point Python knows:

result = {
"status": "unpaid",
"amount": 250,
}

But remember:

The model does not automatically know what happened inside your Python process.

We have to send the result back.

Conceptually:

MODEL:
Call get_invoice_status(4812)
PYTHON:
Executes function
TOOL RESULT:
{
status: unpaid,
amount: 250
}
MODEL:
Now I can answer the user.

This is the critical loop.


We send a function_call_output.

tool_output = {
"type": "function_call_output",
"call_id": tool_call.call_id,
"output": json.dumps(result),
}

That call_id matters.

It connects:

THIS TOOL RESULT

to:

THAT TOOL REQUEST

Then we call the model again:

final_response = client.responses.create(
model="gpt-5.5-2026-04-23",
instructions=INVOICE_INSTRUCTIONS,
previous_response_id=response.id,
input=[tool_output],
tools=tools,
tool_choice="none",
parallel_tool_calls=False,
)

The Responses API supports feeding tool-call outputs back as function_call_output items, and the application’s orchestration code manages the tool-call loop explicitly. OpenAI function-calling guidance

Now:

print(final_response.output_text)

might produce:

Invoice 4812 has not been paid yet. The outstanding amount is $250.

previous_response_id supplies the earlier response history. Top-level instructions must be supplied again when we need the same guidance. tool_choice="none" asks for an answer without another tool request in this one-cycle example. The full example checks that the response completed and actually contains usable final text. Conversation-state guidance

Now the model finally had enough information to answer.


Here is the complete small example. It uses the course’s reviewed SDK/model baseline. It shows at most one tool-request/result cycle, with explicit unsuccessful-response checks. These exceptions stop a teaching script; Lesson 6 explains application error handling.

import json
from openai import OpenAI
client = OpenAI()
INVOICE_INSTRUCTIONS = """
Help answer invoice questions.
Use the invoice tool when invoice data is needed.
"""
def get_invoice_status(invoice_id: int) -> dict:
invoices = {
4812: {
"status": "unpaid",
"amount": 250,
},
4813: {
"status": "paid",
"amount": 175,
},
}
return invoices.get(
invoice_id,
{"error": "invoice_not_found"},
)
tools = [
{
"type": "function",
"name": "get_invoice_status",
"description": "Look up the current status of an invoice.",
"parameters": {
"type": "object",
"properties": {
"invoice_id": {
"type": "integer",
}
},
"required": ["invoice_id"],
"additionalProperties": False,
},
"strict": True,
}
]
response = client.responses.create(
model="gpt-5.5-2026-04-23",
instructions=INVOICE_INSTRUCTIONS,
input="Has invoice 4812 been paid?",
tools=tools,
parallel_tool_calls=False,
)
if response.status != "completed":
raise RuntimeError("Model response did not complete.")
if any(
part.type == "refusal"
for item in response.output
if item.type == "message"
for part in item.content
):
raise RuntimeError("Model refused the request.")
tool_calls = [item for item in response.output if item.type == "function_call"]
if len(tool_calls) > 1:
raise ValueError("This introductory example expects at most one tool call.")
if not tool_calls:
final_response = response
else:
tool_call = tool_calls[0]
if tool_call.name != "get_invoice_status":
raise ValueError("Unknown tool")
arguments = json.loads(tool_call.arguments)
if (
not isinstance(arguments, dict)
or set(arguments) != {"invoice_id"}
or type(arguments["invoice_id"]) is not int
):
raise ValueError("Invalid invoice lookup arguments")
result = get_invoice_status(invoice_id=arguments["invoice_id"])
final_response = client.responses.create(
model="gpt-5.5-2026-04-23",
instructions=INVOICE_INSTRUCTIONS,
previous_response_id=response.id,
tools=tools,
tool_choice="none",
parallel_tool_calls=False,
input=[
{
"type": "function_call_output",
"call_id": tool_call.call_id,
"output": json.dumps(result),
}
],
)
if final_response.status != "completed":
raise RuntimeError("Final response did not complete.")
if any(item.type == "function_call" for item in final_response.output):
raise RuntimeError("Unexpected further tool request.")
if any(
part.type == "refusal"
for item in final_response.output
if item.type == "message"
for part in item.content
):
raise RuntimeError("Model refused the final answer.")
answer = final_response.output_text
if not answer.strip():
raise RuntimeError("Model returned no final answer.")
print(answer)

Ignore elegance for now.

Actually, I prefer that it’s slightly repetitive.

You can see every step.


This is the part I want you to really internalize.

The user says:

Has invoice 4812 been paid?

Python sends:

USER REQUEST
+
TOOL DESCRIPTION

to the model.

The model returns:

FUNCTION CALL REQUEST:
get_invoice_status
invoice_id = 4812

Python confirms the response completed without a refusal, then sees:

function_call

Python checks:

Is get_invoice_status allowed?

Yes.

It parses the JSON arguments:

{"invoice_id": 4812}

Then it checks that the object has exactly invoice_id and that its value is an integer, before calling the lookup function.

Then Python executes:

get_invoice_status(4812)

Result:

{
"status": "unpaid",
"amount": 250,
}

Python sends the result back with the original response ID and the matching call_id, supplies the same instructions, and disables further tool requests for this final call.

The model now sees:

Earlier question:
Has invoice 4812 been paid?
I requested:
get_invoice_status(4812)
Tool returned:
status = unpaid
amount = 250

After Python checks the final response’s status, refusal items, and nonempty text, it can display an answer such as:

Invoice 4812 is unpaid.

That is function calling.

No magic.


Structured Output looked like this:

MODEL
↓
DECISION OBJECT
↓
PYTHON

Tool calling looks like this:

MODEL
↓
TOOL REQUEST
↓
PYTHON
↓
REAL FUNCTION
↓
TOOL RESULT
↓
MODEL

Structured output says:

Return information in a shape I understand.

Tool calling says:

If you need a capability, request it using a shape I understand.

Closely related.

Different jobs.


Look again:

{
"name": "get_invoice_status",
"description": "Look up the current status of an invoice.",
"parameters": {
...
}
}

This should remind you of an API contract.

The model doesn’t need to know:

which database you use
which ORM you use
which SQL query runs
which service class exists

It only needs:

TOOL:
get_invoice_status
INPUT:
invoice_id
OUTPUT:
invoice information

That’s abstraction used properly.

Your actual application might eventually look like:

def get_invoice_status(invoice_id: int):
invoice = invoice_service.get(invoice_id)
return {
"status": invoice.status,
"amount": invoice.amount,
}

The model still sees the same tool.


Imagine defining:

"description": "Gets stuff."

The model has very little information about when to use it.

Better:

"description": """
Look up the current status and amount of an invoice
using its invoice ID. Use this when answering questions
about whether a specific invoice has been paid.
"""

You’re effectively documenting an API for the model.

Good tool definitions answer:

WHAT does this tool do?
WHEN should it be used?
WHAT arguments does it require?

This is not prompt trickery.

It’s interface design.


Our current tool is read-only:

get_invoice_status()

It retrieves information.

But tools could also do:

send_email
cancel_order
update_customer
delete_document
issue_refund
publish_article

Now the stakes change enormously.

Consider:

def issue_refund(order_id: int):
...

If we expose that tool, the model could request:

issue_refund(order_id=123)

You should not automatically conclude:

model requested refund
↓
refund immediately

Instead:

model requested refund
↓
validate request
↓
check authorization
↓
perhaps require human approval
↓
execute

That’s why Lesson 7 will be entirely about permissions and human approval.


Suppose the model asks:

cancel_order(
order_id=123,
)

The schema may guarantee that order_id is an integer.

It does not guarantee:

order 123 exists
current user owns order 123
order 123 can still be cancelled
current user has cancellation permission

Normal application logic must still enforce all of that.

Think of tool arguments almost like browser input.

Your FastAPI instincts apply again.

The client says:

DELETE /documents/123

You don’t say:

Well, they requested it, so clearly they’re allowed.

You validate.

Same with the model.


Instead of putting authorization logic inside the model prompt:

Please only cancel orders the user owns.

put it in Python.

def cancel_order(
order_id: int,
current_user_id: int,
) -> dict:
order = find_order(order_id)
if order is None:
return {"error": "not_found"}
if order.user_id != current_user_id:
return {"error": "forbidden"}
if order.status == "shipped":
return {"error": "cannot_cancel"}
perform_cancellation(order)
return {"status": "cancelled"}

current_user_id in that wrapper comes from the authenticated application, not from model-generated arguments. find_order() and perform_cancellation() are assumed service helpers; this is a permissions excerpt, not a second complete runnable program.

The model can reason.

Python enforces.

That’s the pattern.


19. One subtle point: tools return information to the model

Section titled “19. One subtle point: tools return information to the model”

The result should generally be useful but compact.

Bad:

return database_row.__dict__

which might expose:

internal IDs
timestamps
private notes
password hashes
implementation metadata
hundreds of irrelevant fields

Better:

return {
"status": invoice.status,
"amount": invoice.amount,
}

Tool output is another interface.

Return what the model needs.

Not your whole internal world.


Right now our program performs one cycle:

ASK MODEL
↓
MODEL REQUESTS TOOL
↓
RUN TOOL
↓
RETURN RESULT
↓
ASK MODEL AGAIN

But what if the model needs another tool?

Suppose:

USER:
If invoice 4812 is unpaid, email the customer.

The sequence could be:

MODEL
↓
get_invoice_status(4812)
PYTHON
↓
returns unpaid
MODEL
↓
send_invoice_reminder(4812)
PYTHON
↓
sends email
MODEL
↓
"The reminder was sent."

Now we can’t hardcode:

call model twice

because sometimes it might require:

1 tool call

sometimes:

3 tool calls

sometimes:

0 tool calls

We need:

WHILE the model requests tools:
execute them
return results

And that is exactly Lesson 4.


Imagine a small customer-support application.

You want the model to be able to check an order.

The real Python function is:

def get_order_status(order_id: int) -> dict:
...

Design the tool interface mentally.

A good answer would be approximately:

{
"type": "function",
"name": "get_order_status",
"description": """
Look up the current status of a customer order.
Use this when the user asks about a specific order.
""",
"parameters": {
"type": "object",
"properties": {
"order_id": {
"type": "integer",
}
},
"required": ["order_id"],
"additionalProperties": False,
},
"strict": True,
}

Then identify who owns each responsibility:

Model:
decides whether order lookup is necessary
Tool schema:
defines how the model requests it
Python:
validates the request
Python:
executes get_order_status()
Application/database:
provides the real information
Python:
returns tool result
Model:
turns the result into a useful answer

If that flow makes sense, you understand function calling.


Tool calling becomes dangerous when you forget that the model is making requests, not issuing trusted commands.

  • Wrong tool selection. The model can choose an inappropriate tool. Your tool design and instructions help, but critical actions still need deterministic checks.
  • Valid arguments, invalid operation. order_id=123 may satisfy the schema while still being unauthorized, nonexistent, or impossible to modify.
  • Tool failures. Databases time out, APIs return errors, files disappear, and services fail. Eventually the model needs to receive useful error results instead of your application crashing.
  • Repeated side effects. If send_email() or issue_refund() gets called twice because of retries, you may send two messages or refund twice. Side-effecting tools need idempotency and stronger controls.
  • Multiple tool calls. Production code should not assume there will always be exactly one function call.
  • Overpowered tools. A tool such as run_sql(query) is vastly more dangerous than get_invoice_status(invoice_id). Prefer narrow capabilities.
  • Dynamic execution. Never turn arbitrary model-generated names or code into unrestricted Python execution. Use an explicit mapping of allowed tools.
  • Huge tool results. Returning entire database records wastes context and may expose data the model should never receive.

We’ll revisit several of these in Lesson 6 and Lesson 7.


The core architecture now looks like:

USER
↓
┌─────────┐
│ MODEL │
└────┬────┘
│
tool request
↓
┌─────────┐
│ PYTHON │
└────┬────┘
│
validate + run
↓
┌─────────┐
│ TOOL │
└────┬────┘
│
result
↓
┌─────────┐
│ PYTHON │
└────┬────┘
│
tool result
↓
┌─────────┐
│ MODEL │
└─────────┘

The sentence I want you to remember is:

The model chooses from capabilities you expose. Python remains the authority that decides what actually executes.

We now have almost every ingredient required for a basic agent:

MODEL → reasoning
TOOLS → capabilities
PYTHON → control

What we’re missing is the mechanism that keeps the process going.

We’ll replace the one-off:

model
tool
model

with:

WHILE not finished:
ask model
execute requested tools
return results

And once you see that loop written in plain Python, most of the mystery around “agents” disappears.