Function Calling

Function calling (also called tool use) is a capability that lets AI models invoke external functions to accomplish tasks they can't do alone.

When a user asks something like "What's the weather in Tokyo?", the model doesn't know current weather. But with function calling, it can:

1. Recognize this requires a weather lookup
2. Generate a structured function call: get_weather(location="Tokyo")
3. Your application executes the function
4. The result is sent back to the model
5. The model incorporates the result into its response

This turns chat models into agents that can take actions: searching databases, sending emails, updating records, calling APIs—anything you define as a function.

1. Define your functions Tell the model what functions exist and what they do:

{
  "name": "get_weather",
  "description": "Get current weather for a location",
  "parameters": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "City name"
      }
    },
    "required": ["location"]
  }
}

2. Model decides to call When processing a user message, the model decides if a function call is needed and which one.

3. Model generates arguments The model outputs structured data with the function name and arguments—not the actual call.

4. You execute the function Your application receives the model's request and executes the actual function.

5. Return results to model Send the function results back. The model generates a natural language response incorporating the data.

OpenAI style:

response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "What's the weather in Tokyo?"}],
    tools=[{
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get weather for a location",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {"type": "string"}
                }
            }
        }
    }]
)

# Check if model wants to call a function
if response.choices[0].message.tool_calls:
    tool_call = response.choices[0].message.tool_calls[0]
    # Execute the function
    result = get_weather(tool_call.function.arguments["location"])
    # Send result back to model
    # ... continue conversation with result

Key considerations:

• Handle the case where no function call is needed
• Validate function arguments before executing
• Handle function execution errors gracefully
• Support multiple sequential function calls if needed

Clear, descriptive names get_customer_orders is better than getData. The model uses names to understand when to call functions.

Detailed descriptions Explain what the function does, when to use it, and what it returns. The model only sees your description.

{
  "name": "search_products",
  "description": "Search the product catalog. Use when the user asks about products, availability, or pricing. Returns product name, price, and stock status."
}

Explicit parameter descriptions Don't assume the model knows what parameters mean:

"parameters": {
  "date": {
    "type": "string",
    "description": "Date in YYYY-MM-DD format"
  }
}

Minimal required parameters Make parameters optional when sensible defaults exist. Fewer required fields = easier for model to call correctly.

Return structured data Return data the model can easily interpret and explain to users.

Single function call User asks a question → model calls one function → model responds with result.

Sequential calls Complex tasks may require multiple functions in sequence:

1. search_flights(from="NYC", to="Paris")
2. get_flight_details(flight_id="UA123")
3. check_seat_availability(flight_id="UA123")

Parallel calls Some models support multiple simultaneous calls:

• get_weather("Tokyo") and get_weather("London") together

Human in the loop For sensitive operations, present the proposed action to users before executing: "I'll send an email to john@example.com. Should I proceed?"

Fallback handling When functions fail or return unexpected results, the model should gracefully explain the issue.

Tool selection With many functions available, the model must choose the right one. Good descriptions are crucial.

Validate all inputs Never trust function arguments from the model. Validate types, ranges, and formats before executing.

Limit scope Only provide functions the AI should be able to call. Don't expose administrative functions to customer-facing agents.

Rate limiting Prevent abuse by limiting how often functions can be called.

Audit logging Log all function calls with inputs and outputs for debugging and security review.

Confirmation for destructive actions Require explicit user confirmation before executing delete, send, or purchase operations.

Injection prevention If function arguments are used in database queries or system commands, sanitize them properly.

Least privilege Functions should have minimal permissions. A function to read orders shouldn't be able to modify them.

Error messages Don't expose sensitive system details in error messages returned to the model.