The hands: tools an agent can call
You will learn
What a tool is, which tools an agent may start at once, and which one waits for your yes.
An agent only reads and writes text. It cannot open a file or run a test by itself. A tool is a function the host runs for it: the agent names the tool, the host checks the name against a list, runs it and sends the result back as text. This spec lists 3 tools: 0 read a file, 1 run the tests and 2 write a file. Reading and testing change nothing, so they run at once; writing changes your project, so it waits for your yes. The loop is capped too: of 9 calls asked in one turn the host lets 5 through, so a stuck agent cannot call tools forever. Plant the bug by setting FREE_BELOW to 3 and the test writing_waits_for_a_yes turns red: writing would run without asking.
Try it
Open the widget and name the two tools that run at once; then run the spec, set FREE_BELOW to 3, and read which test fails. Put the line back and run it again.
Three tools, which run at once and which wait for a yes, and the cap on calls in one turn. Lesson 20 of the Vibecoding from zero course.
specs/vibecoding/agent_hands.t27
// SPDX-License-Identifier: Apache-2.0
; specs/vibecoding/agent_hands.t27 -- vibecoding lesson 20: the hands of an agent, tools it can call.
; An agent only reads and writes text. A tool is a function the host runs for it: the agent names
; the tool, the host checks the name against a list, runs it and sends the result back. Tool ids:
; 0 read a file, 1 run the tests, 2 write a file. The first two run at once; writing waits for the
; owner to say yes. The loop is capped so a stuck agent cannot call a tool forever.
; Run the tests, then plant the bug named at the bottom and watch one test turn red.
module vibecoding_agent_hands;
pub const TOOL_READ : u8 = 0;
pub const TOOL_TEST : u8 = 1;
pub const TOOL_WRITE : u8 = 2;
pub const TOOL_COUNT : u8 = 3;
; A tool with an id below this one runs without asking.
pub const FREE_BELOW : u8 = 2;
; The agent asked for this many calls in one turn; the host lets this many through.
pub const MAX_CALLS : u8 = 5;
pub const ASKED_CALLS : u8 = 9;
pub const RUN_CALLS : u8 = 5;
test reading_runs_at_once {
assert TOOL_READ < FREE_BELOW;
}
test running_the_tests_runs_at_once {
assert TOOL_TEST < FREE_BELOW;
}
; The negative control. Writing is not free: its id is not below FREE_BELOW, so the host asks
; the owner first. Plant the bug by setting FREE_BELOW to 3: this test turns red.
test writing_waits_for_a_yes {
assert TOOL_WRITE >= FREE_BELOW;
}
test every_tool_has_an_id_in_the_list {
assert TOOL_WRITE < TOOL_COUNT;
assert TOOL_COUNT == TOOL_WRITE + 1;
}
test the_loop_is_capped {
assert ASKED_CALLS > MAX_CALLS;
assert RUN_CALLS == MAX_CALLS;
}
All lessons
Module 1 · What vibecoding is
You describe, an agent writes, you run it and check. What a program is, and five myths put to a test.
Module 2 · Your desk
An editor with an agent beside it, ten terminal commands, and reading an error message.
Module 3 · Save points with git
A commit is a save point, a branch is a safe try, and a key is a pair of which one stays private.
Module 4 · Prompting
The parts of a prompt, an example in place of an adjective, and one small step at a time.
Module 5 · The working loop
Four phases from idea to ship, the loop of ask, run, read and fix, and what to do when it is stuck.
Module 6 · A test as the judge
A test says yes or no, a planted bug shows the test works, and a diff is read before it is accepted.
Module 7 · The parts of an agent
What an agent answers with, what it can do with tools, and what it keeps between messages.
Module 8 · A first bot
A bot is a message loop, a bot comes from a spec, and a secret stays out of the repository and the prompt.
Module 9 · Your own project
A spec for your own idea, one thing measured after it runs, and an honest plan for the next month.