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.
1. Start with an ordinary Python function
Section titled “1. Start with an ordinary Python function”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.
2. The model cannot see this function
Section titled “2. The model cannot see this function”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.
3. First, describe the tool to the model
Section titled “3. First, describe the tool to the model”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 knowwhether 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
4. Now give the model the tool
Section titled “4. Now give the model the tool”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.
5. What comes back from the model?
Section titled “5. What comes back from the model?”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
6. Python receives the request
Section titled “6. Python receives the request”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_callNow we find the function call.
tool_call = None
for item in response.output: if item.type == "function_call": tool_call = item breakThen:
print(tool_call.name)might give:
get_invoice_statusAnd:
print(tool_call.arguments)might give:
{"invoice_id":4812}Important:
tool_call.argumentsis JSON text.
So we parse it.
import json
arguments = json.loads(tool_call.arguments)Now:
argumentsis:
{ "invoice_id": 4812}7. Python executes the function
Section titled “7. Python executes the function”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: unpaidThat 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_databaserun_shell_commandread_secret_filewhatever_function_exists_in_pythonYour program controls capability.
This is one of the most important security ideas in agent engineering.
9. Now the model needs the result
Section titled “9. Now the model needs the result”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.
10. Return the tool result to the model
Section titled “10. Return the tool result to the model”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 RESULTto:
THAT TOOL REQUESTThen 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.
11. Put the whole thing together
Section titled “11. Put the whole thing together”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 = responseelse: 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_textif 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.
12. Trace execution slowly
Section titled “12. Trace execution slowly”This is the part I want you to really internalize.
The user says:
Has invoice 4812 been paid?First API call
Section titled “First API call”Python sends:
USER REQUEST
+
TOOL DESCRIPTIONto the model.
The model returns:
FUNCTION CALL REQUEST:
get_invoice_statusinvoice_id = 4812Python
Section titled “Python”Python confirms the response completed without a refusal, then sees:
function_callPython 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,}Second API call
Section titled “Second API call”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 = unpaidamount = 250After 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.
13. Compare this with Lesson 2
Section titled “13. Compare this with Lesson 2”Structured Output looked like this:
MODEL ↓DECISION OBJECT ↓PYTHONTool calling looks like this:
MODEL ↓TOOL REQUEST ↓PYTHON ↓REAL FUNCTION ↓TOOL RESULT ↓MODELStructured 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.
14. The tool definition is an interface
Section titled “14. The tool definition is an interface”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 usewhich ORM you usewhich SQL query runswhich service class existsIt only needs:
TOOL:get_invoice_status
INPUT:invoice_id
OUTPUT:invoice informationThat’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.
15. Tool descriptions matter
Section titled “15. Tool descriptions matter”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 invoiceusing its invoice ID. Use this when answering questionsabout 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.
16. Tools can read or change things
Section titled “16. Tools can read or change things”Our current tool is read-only:
get_invoice_status()It retrieves information.
But tools could also do:
send_emailcancel_orderupdate_customerdelete_documentissue_refundpublish_articleNow 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 immediatelyInstead:
model requested refund ↓validate request ↓check authorization ↓perhaps require human approval ↓executeThat’s why Lesson 7 will be entirely about permissions and human approval.
17. The arguments are requests, not truth
Section titled “17. The arguments are requests, not truth”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 permissionNormal 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/123You don’t say:
Well, they requested it, so clearly they’re allowed.
You validate.
Same with the model.
18. A better tool wrapper
Section titled “18. A better tool wrapper”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 IDstimestampsprivate notespassword hashesimplementation metadatahundreds of irrelevant fieldsBetter:
return { "status": invoice.status, "amount": invoice.amount,}Tool output is another interface.
Return what the model needs.
Not your whole internal world.
20. We’re one step away from an agent
Section titled “20. We’re one step away from an agent”Right now our program performs one cycle:
ASK MODEL ↓MODEL REQUESTS TOOL ↓RUN TOOL ↓RETURN RESULT ↓ASK MODEL AGAINBut 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 twicebecause sometimes it might require:
1 tool callsometimes:
3 tool callssometimes:
0 tool callsWe need:
WHILE the model requests tools: execute them return resultsAnd that is exactly Lesson 4.
Short exercise
Section titled “Short exercise”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 answerIf that flow makes sense, you understand function calling.
What breaks in production?
Section titled “What breaks in production?”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=123may 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()orissue_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 thanget_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 takeaway
Section titled “The takeaway”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 → reasoningTOOLS → capabilitiesPYTHON → controlWhat we’re missing is the mechanism that keeps the process going.
Next: Lesson 4 — The Agent Loop
Section titled “Next: Lesson 4 — The Agent Loop”We’ll replace the one-off:
modeltoolmodelwith:
WHILE not finished: ask model execute requested tools return resultsAnd once you see that loop written in plain Python, most of the mystery around “agents” disappears.