Tool / function calling

How an LLM uses your code. The model never runs anything itself — it asks you to.

What tool calling actually does

Tool calling is the mechanism that lets an LLM use your code without ever running any of it. The model produces a structured request — "call get_weather with city='Paris'" — and your application runs the function and feeds the result back into the conversation. The model's next reply factors that result in.

That one mechanism is the bridge between a language model and the rest of your system. Databases, APIs, calculators, email senders, internal services — anything you can wrap as a function, the model can use. It's also the foundation everything called an "agent" is built on.

That's the whole concept. Below: the exact request shape, how to write good tool descriptions, and the failure modes that hit production.

When you'd reach for it

Whenever the model needs information or capabilities outside its head:

• Live data — current weather, stock prices, your inventory, today's calendar.
• Exact computation — calculators, code execution, SQL queries.
• Side effects — sending email, creating tickets, updating records (with guardrails).
• Routing — turning the model into a dispatcher across a fixed set of capabilities.

You wouldn't reach for tool calling on pure-text tasks (summarisation, rewriting, classification) — adding tools there just adds latency and surface area for bugs.

How it's actually built

The flow is six steps, alternating between you and the model:

What's the weather in Paris right now? And what's 17 × 42?

A tool definition is just a name + description + parameter schema:

WEATHER_TOOL = {
  "name": "get_weather",
  "description": "Get the current weather for a city. Returns temperature in °C.",
  "input_schema": {
    "type": "object",
    "properties": {
      "city":    {"type": "string", "description": "City name, e.g. 'Paris'"},
      "country": {"type": "string", "description": "ISO 3166 alpha-2 code, e.g. 'FR'"},
    },
    "required": ["city"],
  },
}

The description fields aren't decoration — they're how the model decides when to call the tool. Treat them like docstrings for a future reader.

Where it bites in real life

Under the hood (optional)

The whole tool-calling round-trip in code: a while loop that asks the model, runs any tools it requests, and feeds results back until the model produces a final text answer. Skip if you don't code — that one-line description is the whole story.

def get_weather(city: str, country: str = None) -> dict:
    return {"temp_c": 14, "condition": "rain"}   # your real implementation
 
TOOLS = [WEATHER_TOOL, CALCULATOR_TOOL]
 
def chat(user_message: str) -> str:
    messages = [{"role": "user", "content": user_message}]
    while True:
        resp = client.messages.create(
            model="claude-sonnet-4-6",
            tools=TOOLS,
            messages=messages,
            max_tokens=1024,
        )
        if resp.stop_reason != "tool_use":
            return resp.content[0].text   # final answer
 
        # Append assistant's tool requests
        messages.append({"role": "assistant", "content": resp.content})
 
        # Run each requested tool
        tool_results = []
        for block in resp.content:
            if block.type == "tool_use":
                if block.name == "get_weather":
                    output = get_weather(**block.input)
                elif block.name == "calculator":
                    output = calculator(**block.input)
                tool_results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": str(output),
                })
        messages.append({"role": "user", "content": tool_results})

Further reading

• Anthropic — Tool use — official guide.
• OpenAI — Function calling — same concept on OpenAI's API.
• Anthropic — Building Effective Agents — designing tools and agentic loops.
• Anthropic Cookbook — tool use examples — runnable end-to-end implementations.