Day 111 · Giving the polymath hands

Tool Use & Function Calling

You will be able to

Explain the full tool loop: request → tool_use → execute → tool_result → final response
Define tools with JSON Schema and write descriptions the model can route on
Implement the loop in runnable code with multiple tools, parallel calls, and error feedback
Return tool errors as is_error results so the model can recover instead of crashing the loop
Apply safety boundaries: input validation, never eval, allowlists, and loop caps

Today's ~120 minutes

Spaced-rep warm-up: due cards (schemas, extraction)	10 min
Tech read: protocol, design, safety boundaries	20 min
Guided: the full loop with three tools	35 min
Guided: routing probes	15 min
Practice: save_note with guardrails	20 min
Project: ToolBelt class + quiz + flashcards	20 min

Builds on: Day 106 — The request & message roles · Day 110 — Schemas & validation · Day 107 — The client wrapper

The analogy

🧸 ELI5⚙ Tech

The polymath knows nearly everything but can DO nothing: no calculator, no weather station, no filing cabinet. Tool use gives them hands — with a twist that surprises everyone the first time: the model never executes anything. You hand the polymath a card describing each tool on the wall — its name, what it is for, what information it needs. When a question needs a tool, the polymath does not act; it writes you a work order: "please run calculator with expression 23.7 times 481." YOUR code runs the tool, writes the result on a slip, and hands it back. The polymath reads the slip and either writes another work order or gives the final answer.

That is the whole trick — a conversation with homework between turns. The model contributes judgment: which tool, what arguments, when to stop. You contribute execution: real code, real APIs, real consequences. Which is why safety lives on your side of the counter: the polymath can ask for anything; your code decides what requests are legal, checks every argument, and refuses politely when the work order says "delete the production database." Give the polymath hands, but you keep the keys.

Why this matters on the job

Tool use is the hinge between "language model" and "system that does things" — it is how LLMs get calculators (fixing Day 96's arithmetic embarrassments), fresh data (fixing the knowledge cutoff), and the ability to act. Every agent you build from Day 120 onward is literally this loop plus planning and memory; MCP (Day 124) is a standard for distributing the tool cards. It is also the sharpest safety boundary you will own: the difference between an assistant that reads your calendar and one that can be tricked into emailing it to a stranger is the engineering you learn today. Modern AI-engineer interviews routinely ask you to whiteboard exactly this loop.

Watch it happen

Giving the polymath hands — one tool call, end to end

step 1 / 5

Your appholds the tools→LLMdecides→Tool runsyour code→LLMcomposes→Answer

✉ messages + tools: [get_weather(city), search_docs(query)]

Your app sends the question plus a MENU of tools (name, description, JSON schema). The model can't run anything — it can only ask.

🎯 Predict modespeed1×

Guided practice

guided 1

The full loop, from scratch

35 min

Create toolbelt.py with the starter: three tools — a safe AST-based calculator, a mock weather lookup, and a mock docs search — plus the complete loop.
Run question 1 ("What is 23.7 * 481 - 19?") and watch the trace: tool_use → your execution → tool_result → final answer.
Run question 2 ("Compare the weather in Lisbon and Warsaw") — observe PARALLEL tool_use blocks in one response, both answered in one user message.
Run question 3 ("Find the retry policy in the docs and calculate the total wait for 4 attempts") — a genuine multi-step chain.
Trigger the error path: ask "What is ln(-5)?" and confirm the is_error result comes back and the model explains the problem instead of crashing.
Read your printed trace end-to-end once — this trace IS the tool-loop visual, produced by your own code.

🐍 python — editable, runs in your browser

import ast
import operator
import anthropic

client = anthropic.Anthropic()

# --- Tool implementations (YOUR side of the counter) ---
OPS = {ast.Add: operator.add, ast.Sub: operator.sub,
       ast.Mult: operator.mul, ast.Div: operator.truediv,
       ast.Pow: operator.pow, ast.USub: operator.neg}

def calculator(expression):
    # AST walker: arithmetic only - NEVER eval model output.
    def ev(node):
        if isinstance(node, ast.Constant) and isinstance(node.value, (int, float)):
            return node.value
        if isinstance(node, ast.BinOp) and type(node.op) in OPS:
            return OPS[type(node.op)](ev(node.left), ev(node.right))
        if isinstance(node, ast.UnaryOp) and type(node.op) in OPS:
            return OPS[type(node.op)](ev(node.operand))
        raise ValueError('only +, -, *, /, ** arithmetic is supported')
    return ev(ast.parse(expression, mode='eval').body)

FAKE_WEATHER = {'lisbon': '24C, sunny', 'warsaw': '11C, rain',
                'tokyo': '18C, cloudy'}

def get_weather(city):
    key = city.strip().lower()
    if key not in FAKE_WEATHER:
        raise ValueError('no data for city: ' + city)
    return FAKE_WEATHER[key]

FAKE_DOCS = {
    'retry policy': 'Retries use exponential backoff: attempt n waits '
                    '2**n seconds, starting at n=1, max 4 attempts.',
    'rate limits': 'Default limit is 60 requests per minute per key.',
}

def search_docs(query):
    hits = [v for k, v in FAKE_DOCS.items() if k in query.lower()]
    return ' | '.join(hits) if hits else 'no matching docs'

TOOL_FNS = {'calculator': lambda i: calculator(i['expression']),
            'get_weather': lambda i: get_weather(i['city']),
            'search_docs': lambda i: search_docs(i['query'])}

TOOLS = [
    {'name': 'calculator',
     'description': 'Evaluate an arithmetic expression (+, -, *, /, **). '
                    'Use for ANY calculation instead of doing math yourself.',
     'input_schema': {'type': 'object',
                      'properties': {'expression': {'type': 'string'}},
                      'required': ['expression']}},
    {'name': 'get_weather',
     'description': 'Get current weather for a city. Use when asked about '
                    'present weather conditions.',
     'input_schema': {'type': 'object',
                      'properties': {'city': {'type': 'string'}},
                      'required': ['city']}},
    {'name': 'search_docs',
     'description': 'Search internal product documentation by keyword query. '
                    'Use for questions about policies or product behavior.',
     'input_schema': {'type': 'object',
                      'properties': {'query': {'type': 'string'}},
                      'required': ['query']}},
]

def run(question, max_iters=6):
    messages = [{'role': 'user', 'content': question}]
    for i in range(max_iters):
        response = client.messages.create(
            model='claude-sonnet-5', max_tokens=1024,
            tools=TOOLS, messages=messages)
        if response.stop_reason != 'tool_use':
            return ''.join(b.text for b in response.content
                           if b.type == 'text')
        messages.append({'role': 'assistant', 'content': response.content})
        results = []
        for block in response.content:
            if block.type == 'tool_use':
                print('  [tool_use]', block.name, block.input)
                try:
                    out = str(TOOL_FNS[block.name](block.input))
                    results.append({'type': 'tool_result',
                                    'tool_use_id': block.id,
                                    'content': out})
                    print('  [result]', out)
                except Exception as e:
                    results.append({'type': 'tool_result',
                                    'tool_use_id': block.id,
                                    'content': 'Error: ' + str(e),
                                    'is_error': True})
                    print('  [error]', e)
        messages.append({'role': 'user', 'content': results})
    return '(stopped: iteration cap reached)'

for q in ['What is 23.7 * 481 - 19?',
          'Compare the current weather in Lisbon and Warsaw.',
          'Find our retry policy in the docs and calculate the total '
          'wait in seconds across all retry attempts.']:
    print('Q:', q)
    print('A:', run(q))
    print()

Ctrl/⌘+Enter runs · Tab indents · numpy/pandas/sklearn auto-load on import (torch and network calls need a local run)

guided 2

Probe the routing

15 min

Ask a question needing NO tool ("What is a context window?") — confirm the model answers directly with stop_reason end_turn. Good routing includes not using tools.
Sabotage a description: change the calculator description to just 'A tool.' and re-ask question 1. Does the model still route correctly, do math itself, or misroute? Restore the description and write the one-line lesson (descriptions are the routing signal — Day 108 specificity again).
Ask something no tool covers ("What is the weather on Mars?") and observe the honest failure path via the error result.
Count iterations for the multi-step question and note how the cap protected you.

On your own

Extend the belt: a real tool with guardrails

20 min

Add a fourth tool with real side effects handled safely: save_note(title, content) that writes a markdown file into a notes/ directory.

Requirements: schema with both fields required; filename derived from the title but sanitized (strip path separators and dots — the model must not be able to write to ../../etc/anything); reject titles over 100 chars with a helpful is_error message; and a dry-run mode flag that reports what WOULD be written. Then ask: "Search the docs for rate limits and save a note summarizing them" — a chain of read tool into write tool.

Hints: path traversal via model-controlled filenames is a real vulnerability class (Day 132 formalizes it); use pathlib and verify the resolved path stays inside notes/; this validate-before-execute pattern is exactly Day 125's approvals story in miniature.

Ship before you stop

toolbelt.py — the loop you will reuse for weeks

Harden today's code into the toolkit: a ToolBelt class where tools register with name, description, schema, and function; a run() that executes the loop with iteration caps, per-call logging to your JSONL format (tool name, args, latency, error flag), and a transcript printer for debugging. Ship the four tools, plus a README section "Adding a tool safely" codifying your rules (validate args, no eval, sanitize paths, cap loops, is_error on failure). Push it. Day 120 imports this file verbatim as the substrate of your first agent; Day 124 replaces its registry with MCP.

Rubric — check what you completed (0/6)

Loop handles single, parallel, and chained multi-turn tool calls correctlyEvery tool_result echoes the right tool_use_id; parallel results ride in one user messageFailures return is_error results and the model demonstrably recoversCalculator uses AST/allowlist evaluation — no eval anywheresave_note sanitizes filenames and rejects traversal attempts (show a blocked attempt)Iteration cap enforced with a graceful message; all calls logged as JSONL

Common mistakes & misconceptions

Believing the API executes tools. It only emits work orders; execution, and therefore all risk, is your code. This also explains why tools can do anything your code can do — no more, no less.
Dropping the assistant's tool_use message from the transcript. The tool_result must follow the assistant turn containing its tool_use_id — mismatched or orphaned ids break the conversation.
Answering parallel tool calls across several user messages. All results for one assistant turn go back in ONE user message, one tool_result block per id.
Raising exceptions out of the loop on tool failure. Return is_error results instead — the model reads errors and self-corrects; your crash handler cannot.
Writing lazy descriptions. The model routes on descriptions; "A tool." causes misrouting that no amount of loop code fixes.
Leaving the loop unbounded. Tool ping-pong can run forever and bill accordingly; cap iterations and spend, and surface the cap as an honest failure.

Knowledge check

Q1. Who executes a tool call?

Q2. A response contains two tool_use blocks. The correct reply is…

Q3. Why return failures as is_error tool_results instead of raising?

Go deeper — curated resources

docsClaude Docs — Tool use overview (the protocol, schemas, tool_choice) ↗30 min articleLilian Weng — LLM Powered Autonomous Agents (tools as the action space) ↗25 min (tool-use sections)docsModel Context Protocol — where tool definitions are heading ↗10 min (skim, full treatment Day 124)

If you have a third hour

tool_choice and forced calls — The API can force a specific tool (tool_choice) — useful for guaranteed-extraction patterns. Explore when forcing beats letting the model route, and how it interacts with structured outputs.

Done means

All three trace types observed: single, parallel, and chained tool calls
Error path verified: is_error result produced and model recovered
save_note blocks a path-traversal attempt (demonstrated, not assumed)
ToolBelt class pushed with logging, caps, and the safety README
Quiz ≥ 2/3

How this connects

← Back: Tool arguments are Day 110's schema-constrained outputs in another costume; the descriptions you wrote are Day 108's specificity doing routing work; and the loop's transcript rules extend Day 106's message anatomy.

Forward →: Day 112 stress-tests everything this week built. Day 120 wraps this exact loop with planning and budgets to make your first agent; Day 124 standardizes tool distribution with MCP; Day 125 adds approvals for side-effect tools; and Day 132 attacks — then defends — this boundary.

Unlocks: D112 Week 16 Checkpoint: The Prompt Lab · D118 Advanced RAG Patterns · D120 Agents I — The Loop · D123 Multi-Agent & Workflow Patterns