Function Calling Explained

The protocol

Function calling is a contract between your code and the model:

1. You provide a list of functions, each with a name, description, and JSON-schema parameter spec.
2. You send the user's message + the function specs to the model.
3. The model either responds with text or with a structured "call function X with args Y."
4. You execute the function (or refuse to).
5. You feed the result back to the model as a new message.
6. The model produces a final answer using the result.

That loop is the entire pattern. Agents are this loop run iteratively.

A function definition (Anthropic-style)

{
  "name": "search_docs",
  "description": "Search internal documentation. Returns up to 10 most relevant chunks.",
  "input_schema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Natural-language search query"
      },
      "max_results": {
        "type": "integer",
        "description": "Number of results, 1-10",
        "default": 5
      }
    },
    "required": ["query"]
  }
}

The model sees this and learns: there's a tool called search_docs; it takes a query and optionally a max_results; it returns documentation chunks.

Tool design — what actually matters

The single biggest determinant of agent reliability is tool quality. Good tools:

• Have one clear job — send_email not do_communication.
• Are typed — string, integer, enum, not "any."
• Have helpful descriptions — describe behavior + edge cases + return format.
• Return useful errors — "file not found at /path/x" beats a 500.
• Are idempotent when possible — safer for retries.

Bad tools (vague names, overlapping scopes, wide-open parameters) cause the model to misuse them, get confused, or loop.

Always validate

The model can return malformed arguments. Don't trust:

def execute_tool(call):
    args = json.loads(call.arguments)
    # Validate against schema BEFORE executing
    if not Schema(...).is_valid(args):
        return {"error": "Invalid arguments"}
    return real_execute(args)

Schema-on-receive is your last line of defense.

The tool-use loop in pseudocode

messages = [user_message]
while True:
    response = model.complete(messages, tools=tools)
    if response.stop_reason == "end_turn":
        return response.text
    if response.stop_reason == "tool_use":
        for call in response.tool_calls:
            result = execute_tool(call)
            messages.append({"role": "tool", "tool_call_id": call.id, "content": result})

That's an agent. Add a max-iteration cap and logging and you have a production loop.

Cross-provider differences (briefly)

• OpenAI: tools=[...], response has tool_calls list.
• Anthropic: tools=[...], response has content blocks of type tool_use.
• Gemini: similar shape; Google calls them "function declarations."
• Open-weights: most modern templates (Llama 3.x, Qwen, DeepSeek) support tool use; the format is provider-specific.

The shape varies; the concept is identical.

When NOT to use it

• For simple deterministic transforms (use code).
• For pure factual recall (use RAG).
• When latency is critical and the tool round-trip dominates (consider doing the work locally).

Function calling is the bridge between LLMs and the world. Get the tools right and you have an agent. Get them wrong and you have a chatbot that wanders.