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.
- 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.
Remember: The model gets the description of each tool, not the code. It decides whether and how to call it.
- Beginner: Function Calling Step by Step
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.
- 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 part | What to write | Bad vs. good |
|---|---|---|
| Name | A short, specific verb phrase | tool1 vs get_order_status |
| Description | What it does and when to use it | orders vs Look up the shipping status of one order by its ID |
| Parameters | Names, types, required or optional, allowed values | data vs order_id (integer, required) |
| Return value | What comes back and its format | Say it returns JSON with status and eta_days |
- 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:
| Check | Why |
|---|---|
| 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.
- 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 job | Example |
|---|---|
| Add authentication | Read the API key from an environment variable on the server, never from the prompt |
| Shape the input | Accept simple arguments like city and build the request |
| Shape the output | Return only the useful fields so the context stays small |
| Handle failures | Timeouts, rate limits and errors become clear messages |
| Limit power | Expose 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.
- 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.
Click to see what a good error looks likeCompare ▼
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.
- 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.
# 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", {}))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
Key Points
The Big Picture
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.