Tool Calling Explained: How AI Agents Use Functions and APIs

A language model on its own can only produce text. Tool calling is the trick that lets that text turn into action — searching, calculating, booking, querying a database — without the model ever touching your systems directly.

How it works in three moves

1. You describe your tools to the model: a name, what it does, and the arguments it takes.
2. The model replies with a tool call instead of normal text when it decides a tool is needed: a tool name plus arguments in JSON.
3. Your code runs the function, then sends the result back to the model, which continues — maybe calling another tool, maybe writing the final answer.

All major model providers support this. The exact field names differ slightly between APIs, but the idea and the JSON schema format are the same everywhere.

Describing a tool with a JSON schema

Here is a tool that checks seat availability for a train. The description is read by the model, so it matters as much as the code:

{
  "name": "check_train_seats",
  "description": "Check seat availability for an Indian Railways train on a date. Use when the user asks if seats are available. Returns available seats per class.",
  "input_schema": {
    "type": "object",
    "properties": {
      "train_number": { "type": "string", "description": "5-digit train number, e.g. 12127" },
      "date":         { "type": "string", "description": "Journey date in YYYY-MM-DD format" },
      "travel_class": { "type": "string", "enum": ["SL", "3A", "2A", "1A", "CC"] }
    },
    "required": ["train_number", "date"]
  }
}

When the user asks "Any 3A seats on 12127 this Friday?", the model responds with something like:

{ "tool": "check_train_seats",
  "arguments": { "train_number": "12127", "date": "2026-11-13", "travel_class": "3A" } }

Your code calls the real railway API (or your database), gets {"3A": 14}, and sends it back. The model then writes: "Yes — 14 seats are available in 3A on Friday."

Running the tool call in Python

import json

def check_train_seats(train_number, date, travel_class="SL"):
    # In a real app this would call an API; here we fake it
    return {"train": train_number, "date": date, "class": travel_class, "available": 14}

TOOLS = {"check_train_seats": check_train_seats}

def run_tool(call):
    name, args = call["tool"], call["arguments"]
    if name not in TOOLS:                       # never run something you did not offer
        return {"error": f"Unknown tool: {name}"}
    try:
        return TOOLS[name](**args)
    except TypeError as e:                      # wrong or missing arguments
        return {"error": f"Bad arguments: {e}"}

call = {"tool": "check_train_seats", "arguments": {"train_number": "12127", "date": "2026-11-13", "travel_class": "3A"}}
print(json.dumps(run_tool(call)))

Notice two habits: only tools in your own dictionary can run, and errors come back as data the model can read and react to, instead of crashing the program.

Writing tools the model uses well

• Clear names and descriptions. Say when to use the tool, not only what it does. Models pick tools from the description.
• Few, focused tools. Five well-defined tools beat twenty overlapping ones. If two tools sound alike, the model will mix them up.
• Constrained arguments. Use enum, formats and required fields so invalid calls are rare and easy to detect.
• Short, structured results. Return the 5 fields that matter, not a 3,000-line raw API response that floods the context window.
• Helpful errors. "Date must be YYYY-MM-DD; you sent 13/11/2026" lets the model fix its own mistake on the next try.

Read tools vs write tools

Separate tools that only read (search, look up an order, read a file) from tools that change things (send email, delete a record, make a payment). Read tools can usually run freely. Write tools deserve limits, logging and often a human "Approve" click. We come back to this in the guardrails lesson.

Where MCP fits

Every app used to write its own glue code for every tool. The Model Context Protocol (MCP), an open standard introduced by Anthropic in late 2024 and now supported widely across AI tools, standardises this. A service exposes its tools once as an MCP server — GitHub, a database, Google Drive, your college ERP — and any MCP-compatible assistant or agent can use them. Think of it as "USB-C for AI tools": one plug shape, many devices.