Tools and Function Calling

Learn how agents use tools: what tools are, how function calling works, how tool schemas describe them, how the model selects a tool, how your code executes it, and how ordinary APIs become tools.

28 minBeginnerCode Examples

The Core Idea: A tool is a function an agent is allowed to call. With function calling, the model does not run anything. It outputs the name and arguments of a tool, and your code runs it and returns the result.

  1. Beginner: What Are Tools?

A language model can only produce text. Tools give it abilities beyond text: reading a database, searching the web, doing exact math, sending an email. A tool is just a normal function in your code that the agent is permitted to use.

Read toolsGet information
Search, database queries, file reads. Low risk.
Compute toolsExact work
Calculators, code runners, data transforms.
Action toolsChange the world
Send email, write file, make payment. Higher risk, needs guards.

Remember: The model gets the description of each tool, not the code. It decides whether and how to call it.

  1. Beginner: Function Calling Step by Step

1
You describe the tools: Name, purpose and parameters are sent to the model with the conversation.
2
The model replies with a call: It outputs the tool name and arguments, for example get_weather with city Delhi.
3
Your code validates and runs it: Check the name and arguments, then execute the real function.
4
You return the result: The tool result is added to the conversation as a message.
5
The model continues: It calls another tool or writes the final answer.

Key point: The model never executes code. It only asks. This is why you can put checks, permissions and limits between the request and the action.

  1. Medium: Tool Schemas

A tool schema is the description the model reads. A clear schema is the most important factor in whether the model uses a tool correctly.

Schema partWhat to writeBad vs. good
NameA short, specific verb phrasetool1 vs get_order_status
DescriptionWhat it does and when to use itorders vs Look up the shipping status of one order by its ID
ParametersNames, types, required or optional, allowed valuesdata vs order_id (integer, required)
Return valueWhat comes back and its formatSay it returns JSON with status and eta_days
Schema tips
Keep the number of tools small, avoid tools that overlap, and put examples of correct input in the description. Vague schemas cause wrong tool calls.

  1. Medium: Tool Selection and Execution

With several tools available, the model selects one by comparing the request with each description. After the model asks for a call, your code does the execution, and it must treat the request as untrusted input:

CheckWhy
Does the tool exist?The model can invent a name
Are all required arguments present and of the right type?Models sometimes omit or mistype arguments
Are the values allowed?For example a refund amount within a limit
Is this action permitted for this user?Permissions belong in code, not in the prompt
Did it succeed?Return a clear error message the model can react to

Good practice: Return helpful errors such as missing argument: b. The model can read the error and fix its next call.

  1. Advanced: APIs as Tools

Most real tools are wrappers around APIs: a weather service, a payment provider, an internal company system. The wrapper hides the HTTP details and exposes a simple function with a clear schema.

Wrapper jobExample
Add authenticationRead the API key from an environment variable on the server, never from the prompt
Shape the inputAccept simple arguments like city and build the request
Shape the outputReturn only the useful fields so the context stays small
Handle failuresTimeouts, rate limits and errors become clear messages
Limit powerExpose a read-only version when writing is not needed

Security: Never give a tool more power than the task needs, and never put secrets in the description or the prompt.

  1. Visual Explanation: Who Decides and Who Executes

The figure splits a tool call into what the model does and what your code does, then lists the checks your code should make.

Part 1 · One Tool CallWho does what
Model sideDecide
Reads the tool descriptions
↓
Chooses get_weather
↓
Outputs the arguments: city = Delhi
↓
A request, not an action
Your code sideExecute
Validates name and arguments
↓
Runs the real function
↓
Sends back: 33C, sunny
↓
Result goes back to the model
Part 2 · Three Checks Before RunningNever trust the request
Exists?
Tool name
Reject names the model invented.
Valid?
Arguments
Right keys, right types, allowed values.
Allowed?
Permission
This user may use this tool.
Click to see what a good error looks likeCompare ▼
Instead of failing silently, return a message like missing argument: b. The model reads it as a tool result and corrects the next call. The code below prints several such errors.

Part 1 shows that the model only produces a request. Part 2 lists three checks before anything runs. Open the bar to see what a helpful error looks like.

  1. Python Implementation: A Tool Registry With Schemas and Validation

This script defines three tools (including an API wrapper), picks a tool for a question, and executes calls with validation so that bad calls return clear errors instead of crashing.

tool_registry.pyPython 3.10+ · standard library only
# Tools for an agent: a registry, schemas, selection, validation and executiondef get_weather(city):    return {"Paris": "18C, cloudy", "Delhi": "33C, sunny"}.get(city, "unknown city") def add(a, b):    return a + b def call_exchange_api(base, target):    # An API used as a tool: a real version would make an HTTP request here    rates = {("USD", "INR"): 83.0, ("USD", "EUR"): 0.92}    return rates.get((base, target), None) TOOLS = {    "get_weather": {"description": "weather temperature forecast city", "params": {"city": str}, "fn": get_weather},    "add": {"description": "add sum total numbers plus", "params": {"a": float, "b": float}, "fn": add},    "exchange_rate": {"description": "currency exchange rate convert money", "params": {"base": str, "target": str}, "fn": call_exchange_api},} def select_tool(question):    # Toy tool selection: score each tool description by word overlap with the question    words = set(question.lower().replace("?", "").split())    scores = {name: len(words & set(t["description"].split())) for name, t in TOOLS.items()}    best = max(scores, key=scores.get)    return best if scores[best] > 0 else None def execute(name, args):    tool = TOOLS.get(name)    if tool is None:        return {"error": "unknown tool: " + str(name)}    for key, kind in tool["params"].items():        if key not in args:            return {"error": "missing argument: " + key}        if not isinstance(args[key], kind):            return {"error": "wrong type for " + key}    return {"result": tool["fn"](**args)} for q in ["What is the weather in Delhi?", "Convert money from USD to INR", "Tell me a joke"]:    print(q.ljust(34), "-> selected:", select_tool(q)) print(execute("get_weather", {"city": "Delhi"}))print(execute("add", {"a": 2.0}))print(execute("add", {"a": "two", "b": 3.0}))print(execute("exchange_rate", {"base": "USD", "target": "INR"}))print(execute("delete_database", {}))
EXPECTED OUTPUT (your numbers may differ slightly)
What is the weather in Delhi? -> selected: get_weather
Convert money from USD to INR -> selected: exchange_rate
Tell me a joke -> selected: None
{'result': '33C, sunny'}
{'error': 'missing argument: b'}
{'error': 'wrong type for a'}
{'result': 83.0}
{'error': 'unknown tool: delete_database'}

The selector matches questions to tool descriptions, and returns nothing for the joke because no tool fits. The last four lines show validation in action: missing argument, wrong type and an unknown tool all return readable errors, while correct calls return results.

Knowledge Check

Question 1: In function calling, who runs the tool?
Question 2: Why return a clear error message when a tool call is invalid?

Key Points

✓Tools are functions an agent may call to read, compute or act.
✓Function calling: the model outputs a tool name and arguments, and your code executes it.
✓A clear schema (name, description, parameters, return value) is the key to correct tool use.
✓The model selects tools by comparing the request with their descriptions, so keep tools few and distinct.
✓Always validate existence, arguments, values and permissions before executing, and return helpful errors.
✓Most tools wrap APIs. Hide secrets, shape inputs and outputs, and give each tool only the power it needs.

The Big Picture

Tools in One Line

Describe the tool → the model requests a call → your code validates and runs it → the result goes back

Good tools turn a text model into something that can actually get things done.

Up Next: A tool is only useful if the agent has the right instructions and context. In Context, Instructions and Structured Outputs you will learn how to feed the model what it needs and how to get reliable replies.