# Tool Calling (Function Calling) Explained

URL: https://aiseason.tech/tool-calling

Tool calling (also called function calling) is how a language model does things instead of only writing about them. You describe your functions to the model; the model replies with the name of a function and the arguments to run; your code runs it and sends the result back. That loop is the engine inside every AI agent. This guide shows the full loop in Python, how structured output fits in, and the mistakes that break it.

| Fact | Value |
| --- | --- |
| Tool calling is | A model returning a structured request to run one of your functions, instead of plain text |
| Also called | Function calling. The two names mean the same thing |
| Who runs the tool | Your code. The model only asks; it never executes anything itself |
| Structured output is | Forcing the model's answer to match a JSON schema, with no function to run |
| You need | Basic Python, an LLM API key and about 30 minutes |
| Where it leads | Put tool calling in a loop and you have an [AI agent](https://aiseason.tech/what-are-ai-agents) |

### What is tool calling in an LLM?

**Tool calling is a feature of language model APIs where the model, instead of answering in text, returns the name of a function you defined and a JSON object of arguments for it.** Your program runs that function, sends the output back to the model, and the model uses it to write its final answer.

A language model on its own can only produce text from what it learned in training. It cannot check today's exchange rate, read your database or send an email. Tool calling closes that gap without giving the model any direct access: the model proposes an action, and your code decides whether and how to carry it out.

### How tool calling works, step by step

1. **Describe your tools.** For each function you send a name, a one-line description and a JSON schema of its parameters.
2. **Send the user's message** together with the tool descriptions.
3. **The model decides.** It either answers in text or returns one or more tool calls: a function name plus arguments.
4. **Your code runs the function** with those arguments and captures the result.
5. **Send the result back** as a tool message linked to the call's ID.
6. **The model answers**, or asks for another tool. Repeat until it replies in plain text.

> The model never runs code. Everything it "does" is something your program chose to execute, which is exactly where you add validation, permissions and logging.

### A complete tool calling example in Python

This example gives a model one tool, a currency converter, and runs the loop until the model has an answer. It uses the OpenAI Python SDK; the same shape works with every major provider.

```python
import json
from openai import OpenAI

client = OpenAI()  # reads OPENAI_API_KEY from the environment

RATES = {"USD": 1.0, "PKR": 278.0, "INR": 84.0}  # demo numbers

def convert_currency(amount: float, from_currency: str, to_currency: str) -> dict:
    usd = amount / RATES[from_currency]
    return {"result": round(usd * RATES[to_currency], 2), "currency": to_currency}

TOOLS = [{
    "type": "function",
    "function": {
        "name": "convert_currency",
        "description": "Convert an amount of money between USD, PKR and INR.",
        "parameters": {
            "type": "object",
            "properties": {
                "amount": {"type": "number"},
                "from_currency": {"type": "string", "enum": ["USD", "PKR", "INR"]},
                "to_currency": {"type": "string", "enum": ["USD", "PKR", "INR"]},
            },
            "required": ["amount", "from_currency", "to_currency"],
        },
    },
}]

messages = [{"role": "user", "content": "How much is 3000 PKR in Indian rupees?"}]

for _ in range(5):  # hard limit so a confused model cannot loop forever
    response = client.chat.completions.create(
        model="gpt-4o-mini", messages=messages, tools=TOOLS
    )
    message = response.choices[0].message
    messages.append(message)

    if not message.tool_calls:      # plain text means the model is done
        print(message.content)
        break

    for call in message.tool_calls:  # run every tool the model asked for
        args = json.loads(call.function.arguments)
        result = convert_currency(**args)
        messages.append({
            "role": "tool",
            "tool_call_id": call.id,
            "content": json.dumps(result),
        })
```

Three details matter. The `enum` stops the model inventing currency codes. The `tool_call_id` ties each result to the request that produced it, which matters when the model asks for several tools at once. The `range(5)` cap is a safety limit you should always have.

### Tool calling vs function calling vs structured output

| Term | What it means | Use it when |
| --- | --- | --- |
| Function calling | The original name for the feature | Same thing as tool calling |
| Tool calling | The model requests one of your functions with arguments | The model needs live data or must take an action |
| Structured output | The model's reply must match a JSON schema you supply | You want data you can parse: extraction, classification, forms |
| JSON mode | The reply is valid JSON but no schema is enforced | Rarely. Prefer structured output with a schema |

Structured output and tool calling use the same machinery, a JSON schema that constrains what the model writes. The difference is intent: a tool call is a request to do something, structured output is the final answer in a fixed shape.

```python
from pydantic import BaseModel
from openai import OpenAI

class Invoice(BaseModel):
    vendor: str
    total: float
    currency: str

client = OpenAI()
completion = client.beta.chat.completions.parse(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Bill from K-Electric, Rs 14,250 due 5 Dec."}],
    response_format=Invoice,
)
invoice = completion.choices[0].message.parsed
print(invoice.vendor, invoice.total, invoice.currency)
```

### How to design tools a model can use well

- **Name tools after the action**: `search_orders`, not `tool_2`. The name is part of the prompt.
- **Write the description for the model.** Say what the tool does, when to use it and when not to.
- **Keep parameters few and typed.** Use enums for fixed choices and mark only truly required fields as required.
- **Return small, clear results.** Send back the ten rows the model needs, not a 5,000-row dump that floods the context window.
- **Return errors as data.** `{"error": "order not found"}` lets the model recover; an exception that crashes your loop does not.
- **Offer fewer tools.** Accuracy drops as the tool list grows. Five sharp tools beat thirty overlapping ones.

### Common tool calling mistakes

| Mistake | What happens | Fix |
| --- | --- | --- |
| No loop limit | The model calls tools forever and burns your budget | Cap iterations and stop with a clear message |
| Trusting arguments blindly | A bad or malicious argument reaches your database | Validate every argument in code before running |
| Skipping the tool result message | The API rejects the next request | Always answer each tool call ID |
| Vague descriptions | The model picks the wrong tool or none | Describe when to use each tool |
| Letting tools do irreversible things silently | An agent deletes or pays without review | Ask a human to approve risky actions |

The last two rows are security issues as much as quality issues. See the [AI agent security guide](https://aiseason.tech/ai-agent-security) for prompt injection and guardrails.

### From tool calling to agents, frameworks and MCP

The loop above is already a small agent. Frameworks package the same loop with extras: [LangChain](https://aiseason.tech/langchain-tutorial) wraps Python functions as tools, [LangGraph](https://aiseason.tech/langgraph-tutorial) adds state and branching, and the [OpenAI Agents SDK](https://aiseason.tech/openai-agents-sdk-tutorial) adds handoffs between agents. The [Model Context Protocol (MCP)](https://aiseason.tech/mcp-course) standardises tool descriptions so one tool server works with many agents.

Write the raw loop once before you use a framework. It takes an hour, and afterwards every framework error message makes sense. The [build an AI agent in Python](https://aiseason.tech/how-to-build-an-ai-agent) tutorial continues from here.

### How AI Season teaches tool calling

Tool calling is taught in the first week of the [AI Season bootcamp](https://aiseason.tech/curriculum) because everything later depends on it: RAG as a tool, LangGraph tool nodes, MCP servers and voice agents. Students write the raw loop by hand before touching a framework. Explanations are in Urdu, code in English. Cohort 02 starts 1st January 2027.

### Frequently asked questions

**What is tool calling in an LLM?**
Tool calling is when a language model returns a structured request to run a function you defined, with arguments, instead of plain text. Your code runs the function and sends the result back so the model can finish its answer.

**Is function calling the same as tool calling?**
Yes. Function calling was the original name; providers now call it tool calling. Both describe the model choosing a function and producing arguments for it.

**Does the model run the function itself?**
No. The model only outputs the function name and arguments. Your application executes the function, which is where you validate inputs and enforce permissions.

**What is the difference between tool calling and structured output?**
Tool calling asks your code to do something and return a result. Structured output makes the model's final answer match a JSON schema. Both rely on JSON schemas; one is an action request, the other is a formatted answer.

**Which models support tool calling?**
Current models from OpenAI, Anthropic and Google all support it, and so do many open models served through Ollama or Groq. Check the provider's documentation for the exact request format.

**How many tools can I give a model?**
APIs accept dozens, but accuracy falls as the list grows. Start with three to five well-described tools and split work across specialised agents if you need more.

---

_Last updated: 2026-11-16. Canonical page: https://aiseason.tech/tool-calling. Source: AI Season (https://aiseason.tech/)._
