Module 2: Core Agent Loop · 4.25h

01 · UNDERSTAND

Day 09 Theory — Tool Calling: Model Requests, Runtime Executes

Why tools change an LLM application

A plain LLM can generate text, but it cannot directly read your production database, reset a password, create a ticket, or query a private API unless the application gives it a controlled way to request those actions.

Tool calling creates that bridge.

The key idea is easy to miss:

The model does not execute the tool. The model proposes a structured tool call. Your application decides whether and how to execute it.

That separation is the security and reliability boundary for everything we build later.

From text generation to action selection

Without tools:

User -> LLM -> text answer

With tools:

User -> LLM
          │
          ├─ final answer
          │
          └─ tool request
                ↓
          application runtime
                ↓
              tool
                ↓
          tool result -> LLM

The model can choose an action, but the runtime owns execution.

What a tool schema does

A tool description usually includes:

a name,
a human-readable description,
a structured input schema.

For example, a lookup_ticket tool might accept a ticket_id string.

The schema helps the model produce machine-readable arguments. It also gives our runtime a type boundary.

But schema validity does not mean the tool call is authorized. A perfectly valid request to reset_password(user_id="alice") can still be forbidden for the current caller.

Tool descriptions influence model behavior

The model selects tools partly from the descriptions we provide. A vague or overlapping tool catalog can lead to wrong selections.

Good tools have:

clear names,
non-overlapping responsibilities where possible,
precise argument descriptions,
explicit constraints.

Do not create one giant do_everything tool simply because it is easy to expose.

The runtime must validate again

Treat model-produced arguments as untrusted input.

Even when provider-native tool calling constrains the shape, the runtime should still validate:

types,
allowed values,
authorization,
resource ownership,
rate limits,
side-effect policy.

The model is not a privileged principal.

Read tools versus write tools

A useful distinction is between tools that only retrieve information and tools that change state.

Examples:

Read:  search_kb, get_ticket, lookup_user
Write: create_ticket, reset_password, approve_refund

Write tools deserve stronger controls because failures can create real-world consequences.

Controls may include explicit user confirmation, role checks, idempotency keys, dry-run modes, or human approval.

Tool output is also untrusted

A tool can return stale data, malformed data, or even attacker-controlled text. Later we will study prompt injection through retrieved/tool content.

The runtime should normalize tool results before feeding them back into the model.

Tool errors belong in the protocol

A tool call may fail because:

arguments are invalid,
permission is denied,
the resource does not exist,
the remote service is unavailable,
the operation times out.

The model needs a bounded, structured observation of the failure—not a raw Python traceback or secret-bearing provider response.

Service Desk connection

Today our Service Desk stops being only a classifier and begins interacting with controlled capabilities. The model may request a ticket lookup or knowledge search, but Python remains the execution authority.

The principle is:

LLMs choose from capabilities; application code validates, authorizes, executes, observes and records the action.

That mental model is the foundation of the agent loop we build tomorrow.

02 · APPLY

Lesson Overview

This is the applied companion for Day 09. Read DAY_09_THEORY.md first for the beginner-first teaching of Tool Calling: Model Requests, Runtime Executes. Then use the real service-desk-day-09/ project to trace, run, debug, and explain the concept.

Service Desk Alignment

Day 09 adds Tool Calling: Model Requests, Runtime Executes to the running Service Desk. Start with tools.py, models.py, db.py, app.py, dispatcher.py, authorization.py, then follow imports and tests to identify the actual runtime path.

Why This Topic Matters

The theory chapter explains why Tool Calling: Model Requests, Runtime Executes is needed. Here the goal is evidence: identify where the capability is implemented, what observable behavior changes, and how the repository proves both success and failure behavior.

System Architecture

This is a repository surface map, not a claim that modules call each other in the displayed order. The modules are ranked by relevance to today's theory.

graph LR
    T[Day 09: Tool Calling - Model Requests, Runtime Executes]
    T --> M1[tools.py]
    T --> M2[models.py]
    T --> M3[db.py]
    T --> M4[app.py]
    T --> M5[dispatcher.py]
    T --> M6[authorization.py]

Follow imports and tests to discover the actual runtime flow.

Repository Implementation Map

Use the real Day 09 repository, not a fabricated sample, to connect theory to implementation.

Theory concepts to locate:

Why tools change an LLM application
From text generation to action selection
What a tool schema does
Tool descriptions influence model behavior

Most relevant implementation modules first:

service_desk/tools.py
service_desk/models.py
service_desk/db.py
service_desk/app.py
service_desk/dispatcher.py
service_desk/authorization.py

Follow imports/calls from the relevant module and confirm behavior in tests. Record input → mechanism → observable output/state → failure evidence.

Code Walkthrough & Mechanics

Read tools.py, models.py, db.py, app.py, dispatcher.py, authorization.py with these theory sections beside you:

Why tools change an LLM application — locate its implementation and evidence.
From text generation to action selection — locate its implementation and evidence.
What a tool schema does — locate its implementation and evidence.
Tool descriptions influence model behavior — locate its implementation and evidence.
The runtime must validate again — locate its implementation and evidence.

For each concept identify the real function/class/protocol boundary, its input/state, its observable result, and the assertion in tests/test_tools.py that proves the behavior. If a concept has no implementation or evidence, record that as a gap rather than inventing one.

Common Mistakes & Debugging Guidance

Use the theory—not generic timeout or .env advice—to decide what can fail today.

Failure lens: revisit Tool descriptions influence model behavior, The runtime must validate again.

Reproduce the smallest case that violates one of those expectations.
Trace the real Day 09 modules until you find the first incorrect state/output/decision.
Use tests/test_tools.py as executable evidence.
Add a regression test if the failure is not already represented.
Fix the smallest responsible boundary and rerun the relevant test before the full suite.

Your debugging explanation must name the topic-specific invariant that failed, not merely say “an exception occurred.”

Practical Lab Instructions

Summarize these theory ideas before opening the implementation:
- Why tools change an LLM application
- From text generation to action selection
- What a tool schema does
- Tool descriptions influence model behavior
Inspect the most relevant real Day 09 modules first:
- service_desk/tools.py
- service_desk/models.py
- service_desk/db.py
- service_desk/app.py
- service_desk/dispatcher.py
- service_desk/authorization.py
Inspect the automated evidence:
- tests/test_tools.py

Establish the baseline:

cd service-desk-day-09
PYTHONPATH=. pytest tests/test_tools.py -q

Trace one theory concept through the actual nested modules and tests.
Run one success case and record input → mechanism → observable result.
Exercise one topic-specific failure/boundary case and name the invariant that protects the system.
Re-run the relevant tests and explain theory → implementation → evidence.

Done when: another student can reproduce your trace without relying on an invented sample.

Key Takeaways

Be able to explain Why tools change an LLM application and point to its implementation/evidence in Day 09.
Be able to explain From text generation to action selection and point to its implementation/evidence in Day 09.
Be able to explain What a tool schema does and point to its implementation/evidence in Day 09.

Knowledge Check & Scenario Questions

Concept: Using Why tools change an LLM application, explain the engineering problem Day 09 is solving without naming a framework as the answer.
Mechanism: How does From text generation to action selection appear in the real project? Start from service_desk/tools.py and name the observable state/output/event that changes.
Failure: For What a tool schema does, describe one incorrect implementation or boundary condition and the evidence you would expect in tests/test_tools.py.
Design review: Which assumption in today's design would you verify before reusing this implementation in a different production system?

Official References

OpenAI Function Calling Guide: https://platform.openai.com/docs/guides/function-calling
Pydantic Field Annotation Specs: https://docs.pydantic.dev/latest/concepts/fields/

03 · EXPLAIN

Interview checkpoint

Explain one design decision from this lesson, the alternative you rejected, and the failure mode or evidence that justified your choice.