8. Phase 6 — Tool Calling & AI Workflows

Estimated time: 2–3 weeks.

8.1 What Tool Calling Adds

RAG helps a model read information. Tools let it interact with systems: query databases, check inventory, search calendars, create tickets, send requests, calculate, or call business APIs. Mechanically, tool calling is the model returning a structured request ("call function get_inventory with argument sku=1234") instead of free text — your code then executes that request and returns the result to the model as another message.

Model output: { "tool_call": "get_inventory", "arguments": { "sku": "1234" } } │ ▼ Your backend validates arguments, checks authorization, executes the real function │ ▼ Tool result returned to the model as a new message │ ▼ Model produces a final natural-language answer using the tool result
Fig 8.1 — The model never directly touches your database; it only ever requests an action, which your code decides whether and how to execute.

8.2 Tool Design Rules

🚧 Critical Rule Never expose unrestricted SQL, shell, filesystem or administrative APIs to a model. A tool named run_sql(query: str) that accepts arbitrary SQL is not a "flexible" tool — it is a direct path from a manipulable text generator to your entire database. Expose narrow, purpose-built tools instead (get_customer_balance(customer_id)), never a raw query interface.

Prerequisite Concept — Why "Authorization in Code, Never in the Prompt"

Intuition. An instruction like "only let managers approve refunds over $500" written into a system prompt is a request to the model, not an enforced rule — a sufficiently manipulated or confused model can still call the tool. Authorization must be a hard check performed by your backend code every time a tool executes, independent of what the model "intended." This mirrors the authentication-vs-authorization distinction from Chapter 3, applied specifically to model-initiated actions.

8.3 Workflows Before Agents

Why order matters. A deterministic workflow follows a fixed sequence of steps, using the model only where judgment is genuinely needed (e.g. extracting fields, drafting text) — control flow stays in your code. An agent (Chapter 9) lets the model itself decide the sequence of steps. Workflows are simpler to test, debug, and secure, so the roadmap recommends exhausting workflow designs before reaching for agent autonomy.

Example: Invoice automation Upload -> extract fields -> validate totals -> find supplier -> check duplicate -> propose accounting entry -> HUMAN APPROVAL -> create invoice -> audit log
Fig 8.2 — Every step is predetermined; the model's role is bounded to specific sub-tasks (extraction, drafting) inside a workflow your code controls.
✅ Preferred Design Use deterministic workflows for predictable business processes. Give the model freedom only inside bounded steps where judgment is useful.

8.4 Project: ERP / Business Tool Assistant

Real-World Example

An internal ERP copilot that a warehouse manager uses to ask "which SKUs are below reorder threshold and who's the supplier for each?" combines two read-only tools (stock levels, supplier lookup) with zero write risk. The same assistant drafting a purchase order is a write action gated behind explicit human approval — the distinction between these two tool classes should be visible in the tool schema itself, not just in application logic, so it's auditable.

Common Questions

Q: Why separate read-only tools from side-effecting tools?
Read tools carry no risk of unintended real-world consequences and can be called freely; write tools can cause financial, data, or business-process damage if called incorrectly, so they warrant stricter validation, approval gates, and audit logging.
Q: What happens if a tool call fails midway through a workflow?
The workflow should catch the failure explicitly, retry if transient, and either roll back any partial state or clearly mark the workflow as failed/paused for human review — silent partial completion is a common source of data inconsistency.
Q: How would you scale tool calling to dozens of business functions?
Group tools by domain, keep each tool single-purpose with a tight schema, and consider a tool gateway layer (Chapter 10) that centralizes authorization, logging, and rate limiting across all tools rather than duplicating that logic per tool.

Interview / Viva Questions

Q: Why must tool arguments be validated independently of the model?
The model can produce malformed, out-of-range, or malicious arguments (intentionally or from injection); independent validation (e.g. Pydantic schema, range/enum checks) is the enforcement layer that prevents bad input from reaching real systems.
Q: What does it mean for a write tool to be idempotent, and why does it matter for AI agents specifically?
Calling it multiple times with the same arguments produces the same end state rather than duplicate side effects; it matters because agent loops or retries can inadvertently call the same tool more than once, and idempotency prevents that from creating duplicate orders, charges, or records.
Q: Why use a deterministic workflow instead of an autonomous agent for invoice processing?
The process is predictable and repeatable with well-defined steps; a deterministic workflow is easier to test, debug, secure, and audit, and reserves model judgment only for the specific sub-tasks (like field extraction) that actually require it.
Q: What should be logged for every tool call, at minimum?
Who requested the action, which model proposed it, the arguments, whether/who approved it, the result, and any error — a complete audit trail sufficient to reconstruct what happened after the fact.

Chapter Summary