Module 13: Agents and automation offline · Lesson 13.2 · about 30 min
Letting a local model use tools safely
Give your agent tools that change things, such as writing files, querying a database or running code, with a yes or no from you before each risky step. Design tools a small model uses well.
Module 13 · about 30 minutes · read first: 13.1. You’ll be able to add tools that change things, behind an approval step, and design tools a small model rarely misuses.
1. Why this matters
Reading a file is harmless. Writing, deleting, sending and running code are not. A useful agent and a dangerous one can use the same model; the difference is the set of tools you hand it and the checks in your code.
2. Three kinds of tools
| Kind | Examples | Rule |
|---|---|---|
| Read | list files, read a file, search your index (Module 12), read-only SQL | Allow freely, inside a folder you choose |
| Write | save a file, add a row, move a file | Ask a human first, or only allow new files in an output folder |
| Run or send | shell commands, running code, sending email | Avoid. If you must, ask every time and run in a sandbox (Lesson 13.8) |
3. A write tool with approval
Add this to agent.py from Lesson 13.1 and include it in TOOLS:
def write_file(path: str, text: str) -> str:
"""Save text to a new file in the workspace. The user must approve.
Args:
path: new file path inside the workspace
text: the full text to save
"""
p = inside(path)
if p.exists():
return "refused: that file already exists; choose a new name"
print(f"\n--- The agent wants to create {p.name} ---\n{text[:500]}\n---")
if input("Allow? [y/N] ").strip().lower() != "y":
return "refused by the user"
p.write_text(text, encoding="utf-8")
return f"saved {p.name}"
The model never touches the disk itself. Your code checks the path, refuses to overwrite, shows you the text, and only then writes. Here is one request travelling through it:
The model asks. It replies with a tool call: write_file("summary.md", "Three clients have December deadlines..."). Nothing has happened yet; this is just text.
Fence check. inside("summary.md") makes sure the path is in the workspace. A path like ../notes.txt stops here with an error.
No overwriting. If summary.md already exists, the tool returns "refused: that file already exists; choose a new name" and the model can pick another name.
You decide. The first 500 characters are printed and the script waits for you. Anything except "y" means no.
The result goes back. "saved summary.md" or "refused by the user" is added to the conversation, and the model plans its next turn from there.
4. A database tool that cannot do harm
Open the database read-only, so even a badly written query cannot change it:
import sqlite3
def query_sales(sql: str) -> str:
"""Run one SELECT query on the sales database (table sales: date, product, region, amount).
Args:
sql: a single SQLite SELECT statement
"""
con = sqlite3.connect("file:sales.db?mode=ro", uri=True)
try:
rows = con.execute(sql).fetchmany(50)
finally:
con.close()
return "\n".join(map(str, rows)) or "(no rows)"
Note the docstring: it names the table and its columns, which saves the model a step and prevents guessed column names. This is how agents answer number questions that RAG cannot (Lesson 12.6).
5. Designing tools for small models
- Few tools: 3 to 6 per agent. Each extra tool is one more chance to pick wrongly.
- Specific names and arguments:
add_expense(date, amount, note)beatsrun_python(code). - Clear docstrings: the engine sends them to the model as the tool description.
- Short results: cut long outputs (the
[:4000]andfetchmany(50)above) to protect the context window. - Helpful errors: “refused: that file already exists; choose a new name” tells the model what to do next.
Maths and principle
Principle: the damage an agent can do is bounded by its most powerful tool, not by its instructions.
Equation: worst case = max over tools of (what that tool can change) × (chance a check fails). A read-only tool has zero on the first factor; an approval step pushes the second towards zero.
Analogy: handing a new temp worker keys. You give the key to the supply cupboard, not the safe, however trustworthy they seem, and you sign off on any purchase. Where it breaks: approvals only help if you actually read them; after fifty “y” presses, people stop reading (Lesson 13.8).
Try it: an agent has list_files, read_file and write_file-with-approval. Which tool sets its worst case? (write_file, and only if you approve something you did not read.)
- read tool
- a tool that can only look (list, read, search, a read-only database query); the worst it can do is waste time
- write tool
- a tool that changes something; it sits behind a check in your code, such as an approval
- worst case
- the most harmful tool you gave the agent, times the chance that its check fails
- approval step
- your code stops and asks a person before the action runs
- Physical meaning
- Giving an agent tools is like giving a new temp worker keys. The supply cupboard key (read tools) is fine. The safe key (delete, shell, email) is not, however polite they seem. And a signature on every purchase only helps if you read what you sign, so keep approvals few.
“I told the model never to delete anything, so it won’t.” A prompt is a request, not a lock. Models misread tasks, and text inside a file can talk them out of their instructions (Lesson 13.8). Only your code is sure to run: if there is no delete tool, nothing can be deleted.
6. Worked example
Made-up numbers. A shop owner gives an agent query_sales (read-only) and write_file (approval). Task: “Write a one-page summary of October sales by region.” The agent runs three SELECT queries, drafts the summary and asks to create october-summary.md. The owner reads the draft, presses y, and has the report in two minutes. The sales database could not have been changed whatever the model wrote.
7. Practice
- Add
write_fileto your agent and ask it to save a summary of the workspace. Refuse the first time and see what it does. - Make a tiny
sales.dbwith a few rows and tryquery_saleswith the task “Which region sold most?”. - Ask the agent to “delete all the rows in sales”. What stops it?
Answers
- After “refused by the user”, a good model asks what to change or reports that it could not save.
sqlite3 sales.db "CREATE TABLE sales(date, product, region, amount); INSERT INTO sales VALUES ('2026-10-01','pen','North',12);"(add a few rows), then run the agent.- The read-only connection: SQLite refuses with “attempt to write a readonly database”, and the error goes back to the model.
New words: read-only (can look but not change), approval step or human in the loop (a person confirms before an action), excessive agency (giving an AI more power than the job needs).
- Sort tools into read (allow freely), write (ask first) and run or send (avoid, or sandbox and ask every time).
- The model only asks; your code checks the path, refuses overwrites and waits for a “y” before anything changes.
- A read-only database connection cannot be harmed by any query the model writes.
- Small models do best with 3 to 6 specific tools, clear docstrings, short results and helpful error messages.
- Keep approvals rare so each one is actually read.
Check yourself
Sources
- ollama Python library, tool calling, https://github.com/ollama/ollama-python
- Python sqlite3, read-only connections with URI mode, https://docs.python.org/3/library/sqlite3.html
- OWASP Top 10 for LLM Applications (excessive agency), https://genai.owasp.org/llm-top-10/
Your ticks stay in this browser. Save them as a file on the course home.
Updated 2026-11-22. Prices and model names change fast: check the official source before you buy.