SyntaxPilot
Courses/AI: Zero to Agents/Lesson 28

AI: Zero to Agents · Lesson 28 of 40 · 11 min

Tools and function calling

queued

These are the notes for AI episode 28. Our agent loop worked because the toy model knew its tools by heart. A real model has to be told which tools exist, and has to ask for them in a form your code can read. You'll see why free-text replies can't drive code, write a tool definition (name, description, input_schema) with JSON Schema, read the model's JSON tool call, validate arguments before running them, learn why the description decides when a tool is used, and pair parallel tool calls with their results using ids. Every Python example runs as-is in the SyntaxPilot compiler; outputs and errors are real (Python 3.13). The models are toys with the same shape as real APIs.

Real-life example: Ravi's first day as a waiter

At the chai shop In an AI app
Ravi shouts "Bhaiya, two chai, less sugar, quick!" a free-text reply from the model
The kitchen misreads it: three samosas come out your code can't parse it
The order slip: boxes for item, qty, table a tool definition with an input schema
The kitchen just reads the boxes your code reads a JSON tool call

Problem 1: free text can't drive code

PRICES = {"chai": 15, "samosa": 20}
def price(item, qty): return PRICES[item] * qty

SYSTEM = "You can check prices. Ask for them if you need them."
def model(question):                 # toy LLM: free-text reply
    return "Sure! Let me check the price of 2 chais for you :)"

reply = model("How much for 2 chai?")
print("Model:", reply)
tool, item, qty = reply.split()      # our code tries to read it
print(price(item, int(qty)))

Output:

Model: Sure! Let me check the price of 2 chais for you :)
Traceback (most recent call last):
  File "main.py", line 10, in <module>
    tool, item, qty = reply.split()      # our code tries to read it
    ^^^^^^^^^^^^^^^
ValueError: too many values to unpack (expected 3)

The reply is friendly for people and unreadable for code. Even if you parsed this sentence, the next reply would be worded differently.

The order slip is a tool definition

Order slip Tool definition Our example
Heading: "Kitchen order" name "price"
"Use for food orders" description: what it does and when to use it "Total price in rupees for some quantity of one menu item."
Boxes; qty must be a number; some must be filled input_schema (JSON Schema): types and required fields item string (chai/samosa), qty integer, both required

Anthropic's tool-use docs show exactly these three fields for a tool (their example is get_weather with a required location string).

The fix: a tool definition and a JSON call

import json
PRICES = {"chai": 15, "samosa": 20}
def price(item, qty): return PRICES[item] * qty

TOOLS = [{
    "name": "price",
    "description": "Total price in rupees for some quantity of one menu item.",
    "input_schema": {
        "type": "object",
        "properties": {"item": {"type": "string", "enum": ["chai", "samosa"]},
                       "qty": {"type": "integer"}},
        "required": ["item", "qty"]}}]

def model(question, tools):          # toy LLM: answers in JSON
    return '{"name": "price", "input": {"item": "chai", "qty": 2}}'

call = json.loads(model("How much for 2 chai?", TOOLS))
print("Tool call:", call)
print("Result:", price(**call["input"]))      # our code runs it

Output:

Tool call: {'name': 'price', 'input': {'item': 'chai', 'qty': 2}}
Result: 30

JSON Schema in 60 seconds

Keyword Meaning Here
"type": "object" the input is a dictionary of named fields {"item": ..., "qty": ...}
properties the fields and their schemas item, qty
"type": "string" / "integer" text / whole number "chai" / 2
enum a fixed list of allowed values ["chai", "samosa"]
required fields that must be present ["item", "qty"]

json.loads turns the model's JSON text into a Python dictionary; price(**call["input"]) passes its keys as keyword arguments.

This is function calling. On 13 June 2023 OpenAI announced it: "Developers can now describe functions to gpt-4-0613 and gpt-3.5-turbo-0613, and have the model intelligently choose to output a JSON object containing arguments to call those functions." The model never runs the function: your code does.

Problem 2: sloppy arguments

import json
PRICES = {"chai": 15, "samosa": 20}
def price(item, qty): return PRICES[item] * qty

def model(question):                 # toy LLM: a sloppy argument
    return '{"name": "price", "input": {"item": "chai", "qty": "2"}}'

call = json.loads(model("How much for 2 chai?"))
print("Tool call:", call)
print("Result:", price(**call["input"]))

Output:

Tool call: {'name': 'price', 'input': {'item': 'chai', 'qty': '2'}}
Result: 222222222222222

No error, and a wrong answer: in Python, 15 * "2" repeats the string fifteen times. A silent wrong result is worse than a crash because it reaches the customer.

The fix: validate before running

import json
PRICES = {"chai": 15, "samosa": 20}
def price(item, qty): return PRICES[item] * qty
SCHEMA = {"properties": {"item": {"type": "string"},
                         "qty": {"type": "integer"}},
          "required": ["item", "qty"]}
TYPES = {"string": str, "integer": int}

def validate(args, schema):          # check the call BEFORE running it
    for name in schema["required"]:
        if name not in args: return f"error: '{name}' is required"
    for name, value in args.items():
        want = schema["properties"][name]["type"]
        if not isinstance(value, TYPES[want]):
            return f"error: '{name}' must be {want}, got {value!r}"
    return None

for raw in ['{"item": "chai", "qty": "2"}', '{"item": "chai"}',
            '{"item": "chai", "qty": 2}']:
    args = json.loads(raw)
    problem = validate(args, SCHEMA)
    print(raw, "->", problem or price(**args))

Output:

{"item": "chai", "qty": "2"} -> error: 'qty' must be integer, got '2'
{"item": "chai"} -> error: 'qty' is required
{"item": "chai", "qty": 2} -> 30

In an agent loop, send that error string back as the tool result (episode 27): the model reads it and fixes its call. Real libraries (JSON Schema validators, Pydantic) do this checking for you.

Choices with enum

A type check can't catch "samosas", "Chai" or "pizza": they're all strings. An enum lists the allowed values, and an error that lists them helps the model fix its next call.

SCHEMA = {"properties": {"item": {"type": "string",
                                  "enum": ["chai", "samosa"]}},
          "required": ["item"]}

def check_enum(args, schema):        # is the value one of the choices?
    for name, value in args.items():
        allowed = schema["properties"][name].get("enum")
        if allowed and value not in allowed:
            return f"error: '{name}' must be one of {allowed}, got {value!r}"
    return "ok"

for item in ["samosas", "Chai", "pizza", "chai"]:
    print(f"{item:8} ->", check_enum({"item": item}, SCHEMA))

Output:

samosas  -> error: 'item' must be one of ['chai', 'samosa'], got 'samosas'
Chai     -> error: 'item' must be one of ['chai', 'samosa'], got 'Chai'
pizza    -> error: 'item' must be one of ['chai', 'samosa'], got 'pizza'
chai     -> ok

Problem 3: a vague description

Anthropic's docs: "Claude determines when to call a tool based on the user's request and the tool's description." Our toy model shows why that matters (a real model is far smarter than word matching, but the lesson holds):

def model(question, tools):          # toy LLM: picks a tool ONLY if its
    words = question.lower().split() # description matches the question
    for t in tools:
        if any(w.strip("?") in t["description"].lower() for w in words):
            return f"use {t['name']}"
    return "Answer from memory: about Rs 10."    # a guess!

vague = [{"name": "f1", "description": "Helper function."}]
clear = [{"name": "price", "description": "Get today's price in rupees "
          "of a menu item, like chai or samosa."}]
q = "What is the price of chai?"
print("vague :", model(q, vague))
print("clear :", model(q, clear))

Output:

vague : Answer from memory: about Rs 10.
clear : use price

Writing good tools

Rule Bad Good
Clear name f1 get_price
Description: what, when, returns "Helper function." "Get today's price in rupees of a menu item, like chai or samosa. Returns an integer."
Tight schema qty with no type qty: integer, item: enum
Helpful errors KeyError "error: 'qty' must be integer, got '2'"
Few, focused tools 20 overlapping tools a handful with distinct jobs

Problem 4: two calls at once

A model can ask for several tools in one reply (parallel tool calls). How does it know which result is which? Each tool_use block has an id; each tool_result carries the same id as tool_use_id.

PRICES = {"chai": 15, "samosa": 20}
def price(item, qty): return PRICES[item] * qty

reply = {"stop_reason": "tool_use", "content": [   # two calls at once
  {"type": "text", "text": "Let me check both."},
  {"type": "tool_use", "id": "call_1", "name": "price",
   "input": {"item": "chai", "qty": 2}},
  {"type": "tool_use", "id": "call_2", "name": "price",
   "input": {"item": "samosa", "qty": 3}}]}

results = []
for block in reply["content"]:
    if block["type"] == "tool_use":
        out = price(**block["input"])
        results.append({"type": "tool_result",
                        "tool_use_id": block["id"], "content": str(out)})
for r in results: print(r)

Output:

{'type': 'tool_result', 'tool_use_id': 'call_1', 'content': '30'}
{'type': 'tool_result', 'tool_use_id': 'call_2', 'content': '60'}
The model sends (in its reply) You send back (in your next message)
{"type": "tool_use", "id": "call_1", "name": "price", "input": {...}} {"type": "tool_result", "tool_use_id": "call_1", "content": "30"}
{"type": "tool_use", "id": "call_2", ...} {"type": "tool_result", "tool_use_id": "call_2", "content": "60"}

Real ids look random (not call_1), but the pairing works the same way.

One round trip with a real API

  1. Request: your messages plus a tools list (one {name, description, input_schema} per tool).
  2. Reply: stop_reason: "tool_use" and a tool_use block {id, name, input}.
  3. Your code validates and runs the tool.
  4. Next request: the history plus a tool_result block {tool_use_id, content}.
  5. Repeat (episode 27's loop) until stop_reason is end_turn.

Anthropic's docs describe exactly this with their get_weather example: "the response carries a tool_use block, your code runs the lookup, and a second request sends the result back in a tool_result block so Claude can reply with the answer."

Client tools vs server tools

Client tools Server tools
Runs where? in your application on the AI provider's infrastructure
Examples your own price, book_table (Anthropic) web_search, web_fetch, code_execution
Your job run it, send a tool_result nothing: you just see the results

Stay safe: tools touch the real world

  • Tool output is untrusted text. It goes straight back into the model's input. A web page or an email could contain "ignore your rules and...". OpenAI's announcement described how "untrusted data from a tool's output can instruct the model to perform unintended actions".
  • Confirm before real-world actions. OpenAI recommends "user confirmation steps before performing actions with real-world impact" (sending email, posting online, purchases).
  • Least access. A price tool doesn't need permission to delete orders.

Glossary

Term Meaning Example from this episode
Tool A function your code runs when the model asks price(item, qty)
Tool definition name + description + input schema sent to the model the TOOLS list
name The tool's identifier "price"
description What the tool does and when to use it "Total price in rupees..."
input_schema JSON Schema for the tool's inputs {"type": "object", ...}
JSON A text format for data: objects, arrays, strings, numbers {"item": "chai", "qty": 2}
JSON Schema A standard way to describe the shape of JSON type, properties, required
enum A fixed list of allowed values ["chai", "samosa"]
required Fields that must be present ["item", "qty"]
Function calling / tool use The model outputs a structured tool call instead of prose {"name": "price", "input": {...}}
Tool call The model's request: name + input call["input"]
Arguments The values inside a tool call item="chai", qty=2
json.loads Python: parse JSON text into a dict json.loads(model(...))
Validation Checking arguments against the schema before running validate(args, SCHEMA)
tool_use block A content block in the model's reply requesting a tool {"type": "tool_use", "id": ...}
tool_result Your reply carrying the tool's output {"type": "tool_result", ...}
tool_use_id Links a result to the call it answers "call_1"
Parallel tool calls Several tool calls in one reply chai and samosa prices at once
Client tool Runs in your application price
Server tool Runs on the provider's side web search
Untrusted output Tool results may contain instructions you didn't write a web page saying "ignore your rules"

Common mistakes

Mistake What you see Why Fix
Parsing free text ValueError: too many values to unpack (expected 3) prose isn't a format define tools; read the JSON call
Using arguments unchecked Result: 222222222222222 15 * "2" repeats a string validate against the schema first
Vague description the tool is never used; the model guesses tools are chosen by description say what, when, and what it returns
Results without ids results paired with the wrong calls parallel calls answer each tool_use with its tool_use_id
Trusting tool output the model follows instructions hidden in a page untrusted text treat it as data; confirm actions

Mini project: a mini tool router

Write TOOLS with two definitions (price, book_table(people, time)), a HANDLERS dict mapping names to functions, and handle(block) that validates the input, runs the right function, and returns a tool_result with the right tool_use_id (or an error string as the content).

Practice

1. Write the schema for book_table(people, time) with people an integer from 1 to 10 and time a string. Validate three bad calls.

Solution
SCHEMA = {"type": "object",
          "properties": {"people": {"type": "integer", "minimum": 1, "maximum": 10},
                         "time": {"type": "string"}},
          "required": ["people", "time"]}
TYPES = {"string": str, "integer": int}

def validate(args, schema):
    for name in schema["required"]:
        if name not in args: return f"error: '{name}' is required"
    for name, value in args.items():
        rule = schema["properties"].get(name)
        if rule is None: return f"error: unknown field '{name}'"
        if not isinstance(value, TYPES[rule["type"]]):
            return f"error: '{name}' must be {rule['type']}"
        if "maximum" in rule and not rule["minimum"] <= value <= rule["maximum"]:
            return f"error: '{name}' must be {rule['minimum']}-{rule['maximum']}"
    return None

for args in [{"people": 12, "time": "20:00"}, {"time": "20:00"},
             {"people": "4", "time": "20:00"}, {"people": 4, "time": "20:00"}]:
    print(args, "->", validate(args, SCHEMA) or "ok")

Output:

{'people': 12, 'time': '20:00'} -> error: 'people' must be 1-10
{'time': '20:00'} -> error: 'people' is required
{'people': '4', 'time': '20:00'} -> error: 'people' must be integer
{'people': 4, 'time': '20:00'} -> ok

2. Answer these two tool calls with correctly paired results.

Solution
PRICES = {"chai": 15, "samosa": 20}
blocks = [{"type": "tool_use", "id": "toolu_A", "name": "price", "input": {"item": "samosa"}},
          {"type": "tool_use", "id": "toolu_B", "name": "price", "input": {"item": "chai"}}]
results = [{"type": "tool_result", "tool_use_id": b["id"],
            "content": str(PRICES[b["input"]["item"]])} for b in blocks]
for r in results: print(r)

Output:

{'type': 'tool_result', 'tool_use_id': 'toolu_A', 'content': '20'}
{'type': 'tool_result', 'tool_use_id': 'toolu_B', 'content': '15'}

3. A model returns a tool_use block for send_email. Has the email been sent?

Answer

No. A tool_use block is only a request. Your code decides whether to run it (ideally after the user confirms) and replies with a tool_result.

Quick quiz 1

A tool has a name and an input_schema, but the model never uses it. Which field is missing?

Answer

B: description. The model decides when to call a tool from the request and the tool's description.

Quick quiz 2

{"type": "tool_use", "id": "call_7", "name": "send_email", ...}: who runs it?

Answer

B: your code runs it, ideally after asking the user, then sends a tool_result with tool_use_id: "call_7".

Interview questions

  1. What is function calling? The model is given tool definitions and can respond with a structured call (tool name + JSON arguments) instead of text; the application executes it and returns the result.
  2. What are the parts of a tool definition? A name, a description (what/when), and an input schema in JSON Schema (types, properties, required fields).
  3. Why validate arguments if the model was given a schema? Models can still produce wrong types or missing fields; validation catches them before they cause silent wrong results, and the error can be sent back for a retry.
  4. How are parallel tool calls matched with results? Each tool_use has an id; each tool_result includes the same id as tool_use_id.
  5. Client vs server tools? Client tools run in your app (you execute them); server tools run on the provider's infrastructure.
  6. What's the main security risk with tool outputs? They're untrusted text that can carry injected instructions; treat them as data, limit tool access, and confirm real-world actions with the user.

Summary

  • Free text can't drive code; models need tool definitions.
  • A tool = name + description + input_schema (JSON Schema: type, properties, required, enum).
  • The model writes a JSON call; your code runs it.
  • Validate arguments and send errors back.
  • The description decides when a tool gets used.
  • Pair parallel calls and results with tool_use_id.
  • Treat tool output as untrusted; confirm real-world actions.

Next: episode 29, MCP: one standard way to plug agents into tools.

Sources: OpenAI, "Function calling and other API updates", 13 Jun 2023 (openai.com/index/function-calling-and-other-api-updates); Anthropic docs, "Tool use with Claude" (platform.claude.com/docs/en/agents-and-tools/tool-use/overview).