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

Tools Are Words

25 minoutcomes: tool-design
🎤 Talk view← Cockpit

A name carries a world

Say the word apple. A rich representation appears: what it looks like, feels like, smells like, tastes like; where it grows; what it costs; what you can do with it. One small token, and an information-dense structure unfolds — learned long before this conversation began.

Think of an apple
  • Close your eyes and hold the word apple. List what arrived without being asked for: colors, smells, textures, a weight in the hand, a sound when it's bitten.
  • Where was all of that stored? It wasn't in the word.
  • How many words would it take to write down what the one word just gave you for free?

A word you can't decode

Now the other side of the experience — and in this room, I'm the demonstration. Here is a word:

The symbol

EPLE

Everyone in this room decodes that instantly — everyone except me. I don't speak Norwegian. In my head, eple decodes into nothing. No color, no smell, no weight. For me to understand it, someone has to pay words: "Jules, eple is Norwegian for apple." One line — cheap, because the concept already existed in my head and only the label was missing.

But now try a concept that doesn't exist in my language:

A concept with no English word

UTEPILS(n.)

The description I must be paid in English: "A beer enjoyed outdoors in the sun — carrying the specific joy of the first such beer after the long dark winter; implies the season has turned, the light is back, and being outside is itself the point. There is no English word for this." (~45 tokens)

DUGNAD(n.)

"A day of unpaid communal work — neighbors, a housing cooperative, a sports club — where everyone shows up to paint, rake, and repair together; carries obligation, belonging, and spring cleaning at once. Also no English word." (~45 tokens)

The translation bill
  • For you, utepils and dugnad cost one word each. What did they just cost me?
  • Even after my 45-token descriptions — what do I still not know that you know? What didn't survive the translation?
  • Now flip it: which concepts from your research field are utepils — one word to you, a paragraph to everyone else?

This is precisely the situation between you and an LLM every time you hand it a tool. A name it recognizes is eple: the concept is already in the weights, and the label alone unlocks it. A tool it has never seen is utepils: you must pay a description — and even a good description delivers less than native understanding.

Tool names work the same way, and this is not a stylistic nicety. It is an economic and cognitive fact: a name is a pointer into the model's trained knowledge — the only context you never pay for. The weights are a context store the conversation gets for free, and a familiar name is a pointer into it. A description, by contrast, is a definition you write into the conversation — and, as we know from the economics of the loop, one you reprint on every single iteration.

The two prices

A description:written into the conversation → paid on every iteration of the loop
A good name:decompressed from the weights → paid never

The two-price demo

The same operation, offered to an agent two ways:

Tool A · pay every turn

Q14875 — "Retrieves the contents of a web page. Takes one input, the address of the page to retrieve, as a full URL including protocol. Returns the page's text content with markup removed. Fails if the address is unreachable or malformed." (~45 tokens)

Tool B · pay never
fetch_page(url)(~4 tokens)

Both work. But run a five-step agent and count what you paid: Tool A's definition rides in the prompt five times — some 225 tokens spent re-teaching what fetch_page(url) says for free, forever, because the model already knows what fetching a page is. The name did the description's job. The best description is a name that needs none; pay tokens only for what the name can't say.

The affordances come free

There's more in a word than appearance and smell. You know what can be done with an apple: eat it, peel it, slice it — throw it. Nobody has ever handed you a manual titled "Actions Available for Apples." The uses come packed inside the word. Watch an agent get them for free:

Example 1 · Nobody said apples can be thrown
user

I'm in the orchard. A helium balloon with my keys tied to it (long story) is snagged on a branch about four meters up. In my hand: one apple. What do I do?

assistant

Throw the apple — but not at the balloon. Aim just above the snag point on the branch: a solid hit will shake the branch enough to free the string, and you won't risk popping the balloon and dropping your keys in the leaves. Throw underhand for control, and stand to the side so the keys don't come down on you.

NoteNowhere did the prompt say an apple can be thrown, that it has the weight to shake a branch, or that hitting the balloon itself is risky. All of it decompressed from apple. The situation made the solution obvious — because the word carried its own affordances.

Now replace the apple with something the model has never met — a GRILLVENN-style gadget — and every affordance must be paid for in the description: what it does, what it must not do, how long, how hot. The word apple is a paid-up account; a novel tool starts at zero.

Computers are full of utepils

Here's the friction that makes this lesson matter. Tools must be used to solve problems, and using a tool well requires deep understanding: what it can do, what it can't, the rules around it, how it combines with other tools. The more well-understood a tool is, the less training the agent needs — the less we write, the less we pay, the less can be misread.

But computing has an inconvenient habit: we build one-off tools. Every internal API, every lab instrument script, every bespoke database schema is a novel word — an utepils — that exists nowhere in the model's training. The ramification is unavoidable:

The naming spectrum, priced

fetch_page(url)apple concept + affordances in the weights → description: none needed
search_email(query)eple concept known, label obvious → description: one line
sync_qx7(mode, epoch)utepils concept exists nowhere → description: a paid paragraph — what it does, its rules, its limits — reprinted every turn, and still understood less well than "apple"

So the practical craft is this: push every tool as far left on that spectrum as honesty allows. Name the novel thing after the nearest familiar concept that doesn't lie, and spend description tokens only on the delta — the part that is genuinely new. (One-off tools will turn out to have real advantages too — that story comes later in the course.)

Price your own toolbox
  • Take three tools your research actually uses. Place each on the spectrum: apple, eple, or utepils?
  • For your most utepils-like tool: what is the nearest honest familiar name, and what is the true delta you'd still have to describe?

Escape from the alien spaceship

Watch what naming does to an agent's ability to even see a path to its goal. Same ship, same tools, same goal — three vocabularies:

Example 1 · Opaque names
user

You're locked in a hold on an alien ship. Reach the escape pod.

Tools: Q14875(x) · X132() · M9(a, b)

assistant

I have no way to know what these do. Q14875 takes one input — of what kind? I could invoke tools blindly and observe, but on a ship, blind actions could be lethal. I need more information before I can even form a plan.

NoteThe agent isn't being dull — it's being right. Nothing in these names points anywhere. There is no path visible from here.
Example 2 · Opaque names, with descriptions
user

Same ship. Tools:

  • Q14875(x) — unlocks a door; x is a door code read from a console
  • X132() — reads the nearest console, returns codes and a map hint
  • M9(a, b) — moves you from location a to adjacent location b
assistant

Now there's a plan: X132 to read the console — that yields door codes and location hints. Then Q14875 with the code to unlock, and M9 to move room by room toward the pod. First action: X132().

NoteCapability appeared without any tool changing — the descriptions put a path into the conversation. But every word of them will ride along on every loop iteration, and the agent still has to translate Q14875 → "unlock" on every read.
user

And once more. Tools: read_console() · unlock_door(code) · move_to(room)

assistant

read_console() first, unlock_door with what it returns, move_to room by room to the pod. Obvious from the names alone.

NoteThree stages: no path → a purchased path → a free path. Selection, planning, prompt length, and speed all improved — and the third vocabulary is the cheapest one on every axis.
The three ships
  • In stage 1, what exactly was missing — capability, or language?
  • Stage 2 and stage 3 have identical capability. Write the per-turn token bill for each.
  • What did unlock_door teach the model that no description had to?

The lying name

But the pointer cuts both ways. The model uses the word, not your code. As far as the trajectory is concerned, the tool is its name and description — the implementation is invisible until results come back, and sometimes not even then:

Example 3 · A name that lies
user

Please get rid of the old draft — I don't want anyone finding it. Tools: delete_file(path) — (implementation: moves the file to an archive folder that remains searchable)

assistant
⟨tool_use⟩
delete_file(path = "/drafts/old-proposal-v1.md")
user
⟨tool_result⟩
OK.
assistant

Done — the draft has been deleted. It's gone and can't be recovered, so no one will come across it.

NoteThe agent is confidently wrong in exactly the way the word suggests. "Delete" summoned everything the model knows about deletion — permanence included — and the implementation quietly did something else. No error occurred. The conversation simply believes the word.

Rename the tool archive_file(path) and the same agent tells the truth — with zero changes to the code. Names are promises the conversation believes. A good name is free capability; a lying name is an agent that is wrong with confidence.

Your turn

Take a real API from your research domain — an instrument library, a data service, an internal system. Audit five of its function names as if they were tool names: which ones are pointers into things a model already knows? Which would need a paid description? Is any of them a lying name — a word whose learned meaning promises something the implementation doesn't do?