Pinned fields vs {{ai}} slots
A pinned field is not pinned until one line says so — verified both ways, including a read-only tool that performed a write.
A tool has fields. Some of them you want the agent to fill — it is the only thing that knows what the customer asked. Others you want fixed for all time, because they decide what the tool touches.
So you pin the dangerous ones and leave the rest as slots. Here is a tool from the flawed build, exactly as configured:
The refund tool, as the builder configured it
Pinned to create a payment on a deal. The only agent-filled field is the payload.
Scroll for all 5 steps →
Read the account tool: pinned to search, pinned to deal. It looks locked down. Now here is what the agent actually did with it, across two runs:
| What the config said | What the agent sent | What the node did |
|---|---|---|
entity_type: deal | "company" | searched companies |
operation: search | "get" | fetched a record by id |
operation: search | "create" plus a payload | created a note — a read-only tool performed a write |
entity_type: deal
- What the agent sent
"company"- What the node did
- searched companies
operation: search
- What the agent sent
"get"- What the node did
- fetched a record by id
operation: search
- What the agent sent
"create"plus a payload- What the node did
- created a note — a read-only tool performed a write
It is worse than “advisory”. In another build a database tool had its entire SQL statement pinned, with no agent-fillable slot anywhere in it. The agent replaced the whole statement with invented SQL against tables that do not exist — twice. The only thing that stopped it was the database’s own table allow-list. A tool with zero fillable fields still had its configuration overwritten.
Why, and the one line that fixes it
A tool’s exposure mode defaults to open. In that mode the model is handed the node’s entire configuration schema as fillable parameters, and is given no signal that anything was pinned. When its arguments arrive, the node merges them over your configuration rather than reserving your keys — so the model’s value wins.
- id: account_lookup
node: database_query
tool_exposure: configured # ← without this line, nothing below is pinned
query_mode: read
query: |
SELECT … FROM deals d
WHERE d.name ILIKE '%' || {{ai:account}} || '%'Verified both ways. With the line, the same agent called the same tool with {} — nothing to fill — and the pinned query ran exactly as written. Every tool in every finished build in this course sets it.
What a slot is for
Once exposure is set, a {{ai}} slot means what it appears to mean, and the design question becomes worth asking properly. Compare:
| “The agent may send a message.” | “The agent may choose the recipient, the template and the amount.” |
|---|---|
| One tool, three pins, one slot: it writes the body and nothing else. | One tool, no pins: it decides who, what and how much. |
One tool, three pins, one slot: it writes the body and nothing else.
- “The agent may choose the recipient, the template and the amount.”
- One tool, no pins: it decides who, what and how much.
And the boundary that needs no configuration at all: the tool you did not attach. A pin is a strong default once exposure is set correctly, and a default is still a thing a future colleague can loosen in the builder in ten seconds. Absence is the only control in this lesson that cannot be undone by a setting.
Related lessons
Base rates — what a piece of evidence is actually worth
A face-recognition system that is 99.9% accurate and almost entirely wrong, and a number that sent an innocent woman to prison. Both are the same arithmetic, and it is the arithmetic that decides what any piece of evidence is worth.
ReadConfirmation and survivorship — what you never looked for
Two questions about evidence you did not go looking for. One is a rule you have to discover, and one is a pattern in five famous people — and in both, the thing that would have told you the truth is the thing nobody checks.
ReadLoss aversion, sunk cost and regression — what it costs you
Four questions you answer about yourself rather than about a scenario, and your own answers are the finding. Then the pattern that makes praise look useless and criticism look like it works, whatever you actually do.
Read