Function Calling (Tool Calling) Explained

What is it?

Function calling (also called tool calling or tool use) is a feature of many model APIs. You send the model your request and a list of function definitions — name, description, and a JSON Schema for arguments. If the model decides a function is needed, its response contains a structured call instead of (or alongside) prose.

Terminology and exact field names differ between providers, but the pattern is the same everywhere. It is the mechanism that implements agent tools.

Why does it matter?

Free-form text is hard for software to act on. Asking a model to "say the order number" and parsing the sentence is brittle. Function calling gives you:

• Machine-readable output — arguments that match a schema you defined.
• A clean boundary between what the model decides and what your code does.
• A path to real capabilities — databases, APIs, calculators — rather than guesses from memory.
• Structured extraction, even without any real function: define a "record_invoice" function and let the model fill its arguments from messy text.

How does it work?

The round trip:

1. Request: your messages + function definitions go to the model.
2. Model decision: it replies with a tool call, e.g. name get_weather, arguments {"city":"Lisbon"}.
3. Your code: parse, validate, authorise, and execute the real function.
4. Return the result to the model as a tool-result message.
5. Final response: the model uses the result to write the answer — or requests another call.

// 2) what the model returns (shape is illustrative; varies by provider)
{ "tool_call": { "id": "call_1", "name": "get_weather", "arguments": { "city": "Lisbon", "unit": "celsius" } } }

// 4) what you send back
{ "role": "tool", "tool_call_id": "call_1", "content": "{\"temp_c\": 21, \"condition\": \"sunny\"}" }

Important points: the model produces text that looks like a call based on the schema — it can choose the wrong function, omit arguments, or invent values, so validate; some APIs can constrain output strictly to the schema, but that guarantees format, not correctness. Many APIs allow multiple calls in one turn.

Example

Task: "Book a table for 4 tomorrow at 7pm."

• Function: create_reservation(party_size:int, datetime:string, restaurant_id:string).
• The model needs the restaurant and today's date. A good design lets it ask a follow-up question or call search_restaurants first, rather than guessing an ID.
• Your code checks the datetime is in the future and the party size is within limits, then calls the booking API and returns a confirmation or an error message the model can explain.

When should I use it?

Use function calling when an application must reliably act on or fetch data, or when you want structured output from unstructured text. If you only need a conversational answer, skip it. If you expect many tools shared across many apps, consider a standard like What is MCP (Model Context Protocol)? (see Function Calling vs MCP).

Common mistakes

• Executing calls without validation or authorisation.
• Vague function descriptions, leading to wrong tool choice.
• Assuming a schema-valid call is a correct call.
• Not handling failure paths: tool errors, timeouts, refusals to call.
• Forgetting that tool definitions cost tokens on every request (What are Tokens in AI?).

Related concepts