Module 4 ended with a precisely drawn boundary: DocuBot knows — it answers with sources about everything the Nubelia documentation says — but it cannot do. The question we left hanging, "How many tasks does my project Atlas have right now?", has no answer in any wiki: the data lives in the Nubelia API, changes by the minute, and no RAG pipeline in the world is going to retrieve it from a collection of chunks. In this lesson we cross that boundary with the mechanism called function calling (or tool use): we describe to the model what functions we have, the model decides when and with what arguments it makes sense to call them, and our code executes them and returns the result. It is probably the worst-named idea in the whole ecosystem — the model doesn't call any function — and at the same time one of the most transformative: it is the piece that separates a chatbot from an assistant that operates on your system. Here we will build DocuBot's first tool, query_project, and finally close the Atlas question.

1. The key idea: the model decides, your code executes
2. Defining a tool: JSON Schema and descriptions that are prompt engineering
3. The complete flow with the SDK: tool_use → execute → tool_result → final answer
4. DocuBot's first tool: query_project against the Nubelia API
5. When the tool fails: errors as a tool_result with is_error
6. tool_choice: automatic, forced and forbidden selection
7. Function calling as the evolution of "asking for JSON" (02-03)

Let's first dismantle the misunderstanding that gives the technique its name. In function calling, the LLM executes absolutely nothing: it has no access to your network, your database, or the Nubelia API. The only thing the model does is what it has always done — generate tokens — except that now it can generate a special type of structured output that means "I want you to call this function with these arguments". Your application reads that request, decides whether to honor it, executes the function with plain, ordinary Python code, and returns the result to the model in a second turn so it can write the final answer.

This division of labor has important consequences, all of them good:

• You are in control. Between the tool_use and the execution there is a line of Python code that you write. You can validate the arguments, apply permissions, log the call, or refuse to execute it. The model proposes; your code disposes.
• Security is reasoned about the same as always. The function you execute is your code running with your application's credentials — the same time-honored principles apply, starting with least privilege: a query tool should use read-only credentials. query_project cannot delete anything because the code that implements it doesn't know how to delete anything. (Write actions and their safeguards arrive in 05-02, and the attacks that exploit tools, in 06-01.)
• The model contributes what no if ever could: understanding that "how's Atlas doing?", "give me the status of my project Atlas" and "¿cuántas tareas abiertas tiene Atlas?" are the same intent, and translating it into a call with correct arguments.

For the model to be able to request a function, you first have to describe it. Every tool is defined with three pieces:

The description deserves a pause: it is prompt engineering. Everything you learned in module 2 applies here — the model will decide whether to use the tool, and with what arguments, based almost exclusively on that text. Compare:

The second version does three things the first doesn't: it delimits the when yes with examples (few-shot in miniature, 02-02), it delimits the when not (it keeps the model from calling the API for documentation questions), and it announces what it returns (the model will write a better final answer knowing what to expect).

Let's see the mechanism with the anthropic SDK we've been using since 03-01 — the flow is conceptually identical in OpenAI, Google or Mistral (the field names change: tools/tool_calls/function, but the dance is the same). The steps:

1. First call: you send the question and the list of tools (the tools parameter).
2. If the model decides to use one, the response arrives with stop_reason == "tool_use" and a content block of type tool_use with name, input (the arguments, already as a dict) and a correlation id.
3. Your code executes the corresponding function.
4. Second call: you resend the full conversation — including the assistant's response with its tool_use block — and add a user message with a tool_result block that references that id.
5. The model, now with the data in hand, writes the final answer (stop_reason == "end_turn").

Steps 2 and 4 hide the two details that cause the most errors: the assistant's tool_use block must go back into the history (otherwise the model doesn't know what it requested), and the tool_result goes inside a message with role user — from the conversation's point of view, the tool's result is something you "tell" the model, and it must be the first content of that message.

Let's actually build it. Since we don't have a deployed Nubelia API in this course, we simulate it with a mock module — the didactic beauty is that the model couldn't care less: all it sees is the tool definition and the results; whether behind it there's a dict or a microservice with a database is invisible from its side of the boundary.

Now the tool definition and its dispatcher, in a new module that will grow throughout this module of the course:

And the complete flow. Notice that we reuse call_with_retries (03-02) and MODEL (03-01) without touching them — tools are just one more parameter of the call. What we do need is a new system prompt: the SYSTEM_DOCUBOT from 02-01 orders the model to rely exclusively on the <documentation> block, and that rule, perfect for RAG, would leave the tool unused. We add a variant to prompts.py (and bump PROMPT_VERSION, as 02-04 demands):

A typical run:

The question that served us in 01-04 as the example of the impossible has just been answered — and with the system's real data, not a plausible hallucination. Three observations before moving on:

• block.input arrives as a dict, already parsed by the SDK. Even so, treat it as untrusted input: the model can pass a project name that doesn't exist or an unexpected value. Our defense lives in get_project (it normalizes and validates), not in trusting the model.
• The result travels as text (hence the json.dumps): a tool_result is content for the model, and compact JSON with descriptive keys is a format it understands beautifully. No prose needed.
• This flow resolves one tool step and finishes. If the model needed to chain several calls (query the documentation and then the API), we would need a loop — exactly the topic of 05-02; let's not get ahead of ourselves.

You already saw the try/except in the previous code; now the philosophy. When a tool fails, the worst option is to let the exception blow up the flow, and the second worst is to return a traceback to the user. The good option is the one we implemented: return the error to the model as a tool_result with is_error: True, with an informative error message — and let the model do what it does best: explain it in natural language.

Question: "how's my project Sapphire doing?". The tool raises ProjectNotFound with our message ("No project named 'Sapphire' exists. Available projects: Atlas, Boreal, Cierzo."), and the model answers something like:

Notice the value chain: the exception's message is also prompt engineering. Because we included the list of available projects in the error, the model can offer alternatives instead of a curt "it doesn't exist". Write your tools' errors knowing that their reader is an LLM that will re-explain them: what failed, why, and what can be done. And the same rule as always: in the error message, no secrets or internal details (paths, SQL, stack traces) — they would go straight into the model's context and, potentially, into the user's answer.

By default the model freely decides whether to use a tool or answer directly. The tool_choice parameter hands you the controls when you need them:

The third case is more useful than it looks and connects directly with the next section: if you force a specific tool, the model always generates a tool_use block with arguments that satisfy your input_schema. In other words: you just obtained guaranteed structured output.

In 02-03 we built DocuBot's JSON contract by requesting the format in the prompt and defending ourselves with clean_json and validate_contract — the model sometimes wrapped the JSON in prose or code fences, and it had to be cleaned. Function calling is the industrialized version of that idea:

The last row is the moral: function calling eliminates the syntactic plumbing, but defensive validation of values doesn't retire — the fact that {"name": "Sapphire"} is perfect JSON doesn't make Sapphire exist. The instinct from 02-03 ("don't trust, validate") is still the law; only where to apply it has changed.

• Forgetting to resend the assistant's turn. The most frequent error in the flow: sending the tool_result without first appending {"role": "assistant", "content": response.content} to the history. The API will reject the request — the tool_result references a tool_use_id that, without that message, doesn't exist in the conversation.
• Skimpy tool descriptions. "Queries a project" produces both too many calls (for documentation questions) and too few (for indirect phrasings). Treat the description with the same rigor you gave SYSTEM_DOCUBOT: when yes, when not, examples.
• Believing the schema validates for you. The input_schema guarantees shape, not truth. Validate the values in your function (does the project exist? is the range reasonable?) as if a stranger had typed them — because, in a way, that's what happened.
• Not covering the no-tool path. With tool_choice: auto, the model can answer directly (stop_reason == "end_turn"). If your code assumes there will always be a tool_use block, that next(...) will raise StopIteration on the first trivial question. Always check stop_reason first.
• Several tool_use blocks in the same turn. The model can request more than one tool at once (parallel calls). Today's flow processes one because its only tool doesn't allow for more; the loop in 05-02 will iterate over all the blocks. If it happens to you before then, respond with one tool_result per tool_use_id.
• Tool errors that help nobody. KeyError: 'sapphire' as a tool_result forces the model to improvise. Write errors with context and alternatives — and without leaking internal information.

1. Second tool: list_projects. Add to tools.py a tool with no arguments that returns the user's list of projects (name and status), and extend run_tool. Test with "what projects do I have right now?" and with "how's Atlas doing?" to check that the model picks the right tool in each case.
2. The error as conversation. With the lesson's code, ask "how many tasks does my project Sapphire have?" and observe the answer. Then deliberately impoverish the ProjectNotFound message (reduce it to "error") and repeat. Compare both final answers and write the conclusion in one sentence.
3. Structured extraction with a forced tool. Define a tool extract_query whose input_schema has category (an enum with the 6 categories of classification_prompt() from 02-02) and project (optional string). Call it with tool_choice: {"type": "tool", "name": "extract_query"} on the question "it won't let me bill the hours for project Boreal" and examine block.input. Which piece from 02-03 did you just replace?

1. Definition and dispatch:

With "what projects do I have?" the model should pick list_projects; with "how's Atlas doing?", query_project. If it gets confused, the lever is the description (not the code!).

2. With the rich error, the model answers with concrete alternatives ("your projects are Atlas, Boreal and Cierzo — did you mean one of those?"). With a bare "error", the model can only say that something failed, or worse, speculate about the reason. Conclusion in one sentence: the quality of the final answer when something fails is bounded by the quality of the error message your tool returns — tool errors are part of the prompt.

3. Schema and call:

You just replaced the "ask for JSON in the prompt + clean_json" tandem: with the forced tool there is no prose to clean and no code fences to strip. validate_contract (the semantic validation) would still have work to do — the enum guarantees that category is one of the six, but nobody guarantees it's the correct one.

DocuBot just did something no RAG could: answer with a piece of data that wasn't written anywhere when the conversation started. The mechanism, once its name is dismantled, is honest and simple — the model decides which function to call and with what arguments, your code executes and returns the result, the model writes — and its pieces are old acquaintances in new clothes: the description is prompt engineering (module 2), the input_schema is the JSON contract of 02-03 with factory-fitted syntactic guarantees, errors as a tool_result with is_error are the graceful degradation of 03-02 narrated to the model, and forced tool_choice gives us, as a bonus, the most robust structured extraction we know. But our answer_with_tool() has a structural limitation that may already be bothering you: it executes one tool step and finishes. If the user asks "is my project Atlas over my plan's task limit?", two lookups are needed — the documentation for the plan's limit, the API for Atlas's tasks — plus a comparison between the two. That is no longer a two-call flow: it's a loop in which the model reasons, acts, observes the result and decides whether it needs to continue. That loop has a name — agent — and it is exactly what we build in the next lesson, where the module 4 RAG will also undergo an elegant transformation: from pipeline to tool.