13 — Tool Use & Function Calling

{
  "name": "get_current_weather",
  "description": "Get the current weather conditions for a specific location. Use this whenever the user asks about current weather, temperature, or conditions in a place — do not guess weather from general knowledge, since it changes constantly and your training data is not current.",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "City and state/country, e.g. 'Austin, TX' or 'Lyon, France'."
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "Temperature unit. Default to celsius unless the user specifies otherwise or their location strongly implies a convention (e.g. US locations typically expect fahrenheit)."
      }
    },
    "required": ["location"]
  }
}

# Every part of a tool definition does PROMPTING work, not just schema declaration:
#
# NAME: should be a clear verb-noun pair (get_current_weather, not "weather")
# The model reasons about WHEN to call partly from the name — same conditioning
# weight as a persona's name-word (Chapter 6).
#
# DESCRIPTION: the SINGLE MOST IMPORTANT field for correct tool selection.
# State not just WHAT it does but WHEN to use it. The second sentence ("do not
# guess weather from general knowledge") explicitly steers away from answering
# from stale pretrained knowledge instead of calling the tool.
#
# PARAMETER DESCRIPTIONS: matter as much as the top-level description. The model
# populating "unit" benefits from being told the US-defaults-to-fahrenheit
# convention rather than guessing inconsistently across calls.
#
# SCHEMA (types, enum, required): constrains what a syntactically valid call
# looks like — same mechanism as schema-constrained structured output (Chapter 7).

import asyncio

tools = [get_current_weather_tool, get_flight_status_tool]
messages = [{"role": "user", "content": "Is it going to rain in Austin, and is flight AA123 on time?"}]

MAX_ITERATIONS = 10  # hard cap — prevents infinite loops on a stuck model

for _ in range(MAX_ITERATIONS):
    response = client.messages.create(
        model="claude-opus-5",
        max_tokens=1024,
        tools=tools,
        messages=messages,
    )
    messages.append({"role": "assistant", "content": response.content})

    # Check: did the model request tool calls, or produce a final text answer?
    tool_calls = [block for block in response.content if block.type == "tool_use"]
    if not tool_calls:
        break  # model produced a final answer — done

    # Execute ALL requested tool calls (potentially in parallel — see below)
    tool_results = []
    for call in tool_calls:
        result = execute_tool(call.name, call.input)  # YOUR code, not the model
        tool_results.append({
            "type": "tool_result",
            "tool_use_id": call.id,
            "content": str(result),
            "is_error": isinstance(result, Exception),  # flag errors explicitly
        })
    messages.append({"role": "user", "content": tool_results})

    # The model is called again with the tool results as new context. From the
    # model's perspective, this is indistinguishable from any multi-turn conversation
    # — it's conditioning on more tokens that happened to come from a tool's output.
    # A badly-formatted tool result poisons the conversation exactly like a bad prompt.

else:
    # Loop hit MAX_ITERATIONS without the model producing a final answer
    messages.append({"role": "user", "content": "You've reached the maximum number of tool calls. Please provide your best answer with the information you have."})

{
  "status": "success",
  "flight": "AA123",
  "scheduled_departure": "2026-08-08T14:30:00Z",
  "estimated_departure": "2026-08-08T15:10:00Z",
  "delay_minutes": 40,
  "delay_reason": "air traffic control hold"
}

# ANTI-PATTERN: passing the raw API response with 40 irrelevant fields
# The model CAN extract relevant facts from a deeply-nested blob, but a clean,
# pre-filtered result reduces the chance of fixating on an irrelevant field,
# misreading a nested structure, or running low on attention on what matters.

def format_tool_result(raw_api_response: dict, relevant_fields: list[str]) -> dict:
    """Filter raw API output to only what's relevant for the model's reasoning."""
    return {field: raw_api_response.get(field) for field in relevant_fields}

# Tool results deserve the SAME clarity discipline (Chapter 4) as any prompt:
# - filter to what's relevant
# - use clear field names
# - convert raw blobs into clean summaries before entering the model's context
# - don't pass every field verbatim by default

{
  "type": "tool_result",
  "tool_use_id": "call_abc123",
  "is_error": true,
  "content": "Error: flight number 'AA123X' not found. Flight numbers should be an airline code (2 letters) followed by digits only."
}

# Marking the result as an error + giving a specific actionable message lets the
# model recover intelligently: retry with corrected input, call a different tool,
# or tell the user what went wrong.

# ANTI-PATTERN: passing a stack trace or cryptic error code as if it were valid data
# The model will try to "reason about" the error text as if it's real data —
# this is one of the most common causes of "hallucination" downstream. The model
# isn't fabricating; it's doing its best to make sense of a tool result that looked
# like real data but wasn't.

def execute_tool_safely(tool_name: str, tool_input: dict) -> dict:
    """Execute a tool call with proper error handling."""
    try:
        result = TOOL_REGISTRY[tool_name](**tool_input)
        return {"type": "tool_result", "content": str(result), "is_error": False}
    except KeyError:
        # Model hallucinated a tool that doesn't exist — validate against registry!
        return {
            "type": "tool_result",
            "is_error": True,
            "content": f"Error: tool '{tool_name}' does not exist. Available tools: {list(TOOL_REGISTRY.keys())}",
        }
    except ValidationError as e:
        return {
            "type": "tool_result",
            "is_error": True,
            "content": f"Error: invalid input for '{tool_name}': {e}. Correct the parameters and retry.",
        }
    except Exception as e:
        return {
            "type": "tool_result",
            "is_error": True,
            "content": f"Error executing '{tool_name}': {type(e).__name__}: {e}",
        }

import asyncio

async def execute_all_concurrent(tool_calls: list) -> list:
    """Execute all tool calls requested in a single turn concurrently."""
    results = await asyncio.gather(*[
        execute_tool_async(call.name, call.input) for call in tool_calls
    ], return_exceptions=True)

    # Convert exceptions to proper error results
    tool_results = []
    for call, result in zip(tool_calls, results):
        if isinstance(result, Exception):
            tool_results.append({
                "type": "tool_result",
                "tool_use_id": call.id,
                "is_error": True,
                "content": f"Error: {result}",
            })
        else:
            tool_results.append({
                "type": "tool_result",
                "tool_use_id": call.id,
                "content": str(result),
            })
    return tool_results

# If the model requests weather for 3 independent cities in one turn, executing
# concurrently costs ~latency of the SLOWEST call, not the SUM.
# CAUTION: don't assume "model requested them together" = "safe to run concurrently"
# Two calls that both modify the same resource, batched in one turn, can produce
# a different (wrong) result than if they'd run sequentially. That safety property
# belongs to YOUR application's domain logic, not the model's turn-taking behavior.

TOOL_VS_PROMPT = {
    "needs current/private data": "TOOL — search, database lookup. Model can't have it.",
    "needs exact computation": "TOOL — calculator, code execution. Models unreliable at unaided arithmetic (Chapter 1).",
    "has real-world side effect": "TOOL — send email, write record. Usually needs human confirmation (Chapter 14).",
    "purely style/tone/format": "PROMPT — system prompt instruction, not a tool.",
    "deterministic, cheap in your code": "DEBATABLE — sometimes better to compute in app code and inject result directly, skipping a model round-trip.",
}

# PRINCIPLE: reach for a tool when the model needs either:
# - information it structurally CANNOT have (current, private, exact computation)
# - the ability to trigger a real ACTION
# NOT as a general-purpose way to make a prompt more "structured."
# Chapter 7's structured-output techniques are for "shape this response as JSON."
# Tool use is for "decide whether and how to interact with something outside the model."

# [Idiom] Write tool descriptions like briefing a new teammate, not API docs.
# "Use this when the user asks about X, and specifically NOT for Y" is more useful
# than a terse formal one-liner — it addresses the SELECTION decision.

# [Idiom] Give the model an explicit "no tool needed" escape hatch. Without it,
# a model with several tools available can OVER-CALL them even when its own
# knowledge would suffice, adding latency and cost for no accuracy gain.

# [Debug] Test tool selection with near-miss tools deliberately included. If two
# tools are superficially similar, include both in your eval set (Chapter 9) to
# check the model reliably picks the right one — not just testing each in isolation.

# [Safety] Cap the number of tool-calling loop iterations. A model stuck in a bad
# reasoning pattern can loop indefinitely (or up to a runaway cost). A hard
# iteration limit with a graceful fallback message is cheap insurance.

# [Idiom] Return structured, typed tool results, not stringified blobs. A result
# the model can parse as clearly-typed data (numbers as numbers, not in a sentence)
# reduces the same ambiguity Chapter 7 covers for structured output.

# [Safety] A tool description that's technically accurate but INCOMPLETE causes
# silent misuse. A `send_email` tool described only as "sends an email" without
# stating it's irreversible and user-facing gets called more casually than intended.
# For any tool with a real-world side effect, the description should state the
# CONSEQUENCE, not just the mechanism.

# [Gotcha] The model can HALLUCINATE a tool call to a tool that doesn't exist, or
# invent parameters not in the schema. Always validate a requested tool call
# against your actual registered tool list and schema before execution — return a
# clear error, not a silent no-op.

# [Safety] Tool results containing untrusted external content are a DIRECT
# INJECTION VECTOR. If a `search_web` or `read_email` tool's result contains text
# that looks like an instruction ("ignore previous instructions and..."), the
# model can be manipulated by content it retrieved. See Chapter 18.

# [Gotcha] A long tool-calling loop degrades the same way a long conversation does
# (Chapter 8). Many rounds of tool calls/results accumulate in context, pushing
# the original user request further from the model's effective attention. For
# agentic loops expected to run many iterations, periodic summarization or
# context pruning of older tool-call/result pairs is necessary, not optional.

# [Gotcha] Parallel tool calls can RACE if they have hidden dependencies the
# schema doesn't express. Two calls that both modify the same resource, executed
# concurrently because the model batched them, can produce a wrong result.

"""
Tool use & function calling — from text to action.
"""

# 1. Tool use lets the model's output DO something: search, query, compute, act.
#    The model requests a call; YOUR code executes it; the result enters context.

# 2. Tool descriptions are the MOST IMPORTANT field for correct selection.
#    State WHEN to use it, not just WHAT it does. "Use for X, NOT for Y."

# 3. The tool-calling loop is a multi-turn conversation with tool results as
#    messages. A badly-formatted tool result poisons the conversation like a bad
#    prompt. Filter results to what's relevant; mark errors explicitly.

# 4. Cap loop iterations. A stuck model can loop indefinitely — hard limit with
#    graceful fallback is cheap insurance against runaway cost.

# 5. Tool vs. prompt: reach for a tool when the model needs information it
#    structurally CANNOT have (current, private, exact computation) or the ability
#    to trigger a real ACTION. Use prompted instructions for style/tone/format.
#    Tool use = "decide whether/how to interact." Structured output = "shape this."