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
- Request: your
messagesplus atoolslist (one{name, description, input_schema}per tool). - Reply:
stop_reason: "tool_use"and atool_useblock{id, name, input}. - Your code validates and runs the tool.
- Next request: the history plus a
tool_resultblock{tool_use_id, content}. - Repeat (episode 27's loop) until
stop_reasonisend_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
- 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.
- 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).
- 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.
- How are parallel tool calls matched with results? Each
tool_usehas an id; eachtool_resultincludes the same id astool_use_id. - Client vs server tools? Client tools run in your app (you execute them); server tools run on the provider's infrastructure.
- 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).