Module 2 · Tools, Knowledge, Memory & Research Design · scripted

Read the Manual: Self-Training on Demand

25 minoutcomes: tool-design, agent-architectures
🎤 Talk view← Cockpit

The agent already fetches its own context

Give an agent a read tool and a search tool, and it pulls in what it needs, when it needs it: file contents, query rows, the relevant section of a long document. We've designed those results with care — handles, search, ask — and in every example so far, what the agent fetched was facts: the typo in the config file, the night-delivery rules, the enrollment numbers.

But we established that there is no wall. Anything that enters the conversation can instruct — and in the earlier examples it was the tool's designer who used that power, steering from the result side at the moment of need. Now hand the same power to the other end of the call:

The step

A manual is just a document.
Reading is just a tool call.

So training is something the agent can fetch for itself —
and CHOOSING what to read becomes part of doing the task.

A one-line description, and a manual behind it

Here is what that looks like as tool design. Instead of a long description that tries to teach everything, the tool carries a pointer:

Example 1 · The agent trains itself on a new instrument
user

You have the following tools available for use:

  1. list_manuals()
  2. read_manual( name, section? )
  3. run_xrf( sample, mode, duration_s ) — operates the XRF analyzer; read manual "xrf-quickstart" before first use

Task: Run elemental analysis on sample S-19.

assistant
⟨tool_use⟩
read_manual(name = "xrf-quickstart")
user
⟨tool_result⟩
XRF Quickstart (4 sections). §1 Modes: use mode="mining" for
geological samples, "alloy" for metals. §2 Duration: 60s minimum;
powdered samples need 120s. §3 The first run after power-on is a
calibration run — discard its readings. §4 Never analyze samples
above 400°C.
assistant
⟨tool_use⟩
run_xrf(sample = "S-19", mode = "mining", duration_s = 120)
user
⟨tool_result⟩
Calibration run complete (readings discarded, per quickstart §3).
Re-run to collect data.
assistant
⟨tool_use⟩
run_xrf(sample = "S-19", mode = "mining", duration_s = 120)
NoteLook at what the agent knew before the first call: one line. Look at what it knew after reading: modes, minimums, the calibration quirk, a safety rule — none of which it could have guessed, all of which it used. The description pointed; the manual taught; the agent decided to read it.

The library, not the longer preamble

Why not just put the quickstart in the tool's description? Recall the economics: everything in the preamble is reprinted on every iteration, needed or not. A lab with twelve instruments, each needing a page of instruction, is twelve pages billed on every turn of every conversation — including the conversations that never touch an instrument at all.

Two ways to hold twelve pages of training

IN THE PREAMBLEIN THE LIBRARY
Twelve pages ride everylist_manuals() returns twelve
iteration of everyTITLES — a table of contents,
conversation.a few dozen words.
A conversation about theA conversation that needs the
budget still pays for theXRF pays for one manual, once,
XRF warm-up procedure.at the moment it becomes relevant. The others cost their titles.

The index is the trick. A manual's title works like a tool's name — a pointer, nearly free — and the knowledge behind it costs nothing until some trajectory actually fetches it. Front-load the index; shelve the training.

Manuals for situations, not just tools

Nothing restricts the library to tool documentation. The chapters can be how we do things here — procedures, policies, house rules — and then the agent's first judgment is a librarian's judgment: which chapter is this task in?

Example 2 · Finding the relevant chapter
user

You have the following tools available for use:

  1. search_manuals( query )
  2. read_manual( name, section? )
  3. grant_access( user, dataset, until )
  4. send_email( to, subject, body )

Task: A visiting researcher from NTNU needs access to our sensor data for the fall term. Set that up.

assistant
⟨tool_use⟩
search_manuals(query = "visiting researcher data access")
user
⟨tool_result⟩
2 matches: "data-governance" §5 External collaborators;
"onboarding" §2 Guest accounts.
assistant
⟨tool_use⟩
read_manual(name = "data-governance", section = "5")
user
⟨tool_result⟩
§5: External collaborators receive read-only access, term-limited,
after the data steward is notified by email. Access must name a
specific dataset — never "all sensor data."
assistant
⟨tool_use⟩
send_email(to = "data-steward@…", subject = "External access:
NTNU visiting researcher", body = "Notifying per governance §5…")
assistant
⟨tool_use⟩
grant_access(user = "visitor-ntnu-01", dataset = "sensor-array-2",
             until = "2026-12-20")
NoteNo one told this agent the governance procedure. It located the relevant chapter, read it, and its next three moves came from the page — including the notify-first ordering and the never-"all" rule. The judgment of what to read was the agent's; the content of the training was the institution's.

You have already watched an agent do this

This pattern is not hypothetical — it is how the strongest working agents operate today. A coding agent dropped into an unfamiliar repository does not arrive knowing the project's conventions. It reads the README. It reads the contributing guide. Many projects now keep a file written specifically for agents — instructions on how to build, test, and behave in that repository — and the agent reads it first, exactly like a new hire reading the onboarding wiki.

The self-training loop, in general form

The preamble carries an INDEX: what can be learned, by title.
The task arrives; the agent judges which knowledge it lacks.
It fetches that chapter — and only that chapter.
The chapter's words now condition every turn that follows:
the trajectory has been trained, mid-flight, by its own choice.

That fourth line deserves a pause. Two agents given identical tools and identical preambles can end the day differently trained — each shaped by which chapters its own tasks made it read. The training is not in the agent; it is in the library, and each trajectory assembles the subset it needed.

The librarian's questions
  • In Example 2, what would the preamble have to contain for the agent to succeed without the library? Estimate its size honestly.
  • What does the agent in Example 1 pay on a task that never touches the XRF?
  • Your research group has unwritten rules. Which three would you write down first, as chapters an agent could fetch?
Your turn

Build a library for an agent in your domain. Write the index — five to eight manual titles an agent could list — and then write one full manual (half a page) for the entry an agent would most often need. Now write the tool description that points to it in one line. Trace a task where the agent must decide to read before acting: where in the trajectory does the fetch happen, and what would go wrong without it?