Tool Design Case Studies

Four cases, one method

Everything so far — names as pointers, descriptions as paid definitions, the tool set as a language — becomes concrete the same way: take one goal, design two tool sets for it, and watch what happens to the trajectory. Four cases. Each ends in a principle you can reuse.

Case 1 · Editing a book

The goal: revise a 300-page manuscript. Two languages for it:

⟨tool_use⟩
read_page(n = 41)

⟨tool_result⟩
[page 41 text: …the duplicated paragraph appears here…]

⟨tool_use⟩
delete_from_page(n = 41, line = 12)

⟨tool_result⟩
OK. Document is now 299 pages.

⟨tool_use⟩
edit_page(n = 87, line = 4, text = "Molde")

⟨tool_result⟩
No match for "Mlde" on page 87.

⟨tool_use⟩
read_toc()

⟨tool_result⟩
ch1: Arrival · ch2: The Harbor · ch3: The Fjord Crossing · …

⟨tool_use⟩
edit_section(id = "ch2", old = "[duplicated paragraph]", new = "")

⟨tool_result⟩
OK.

⟨tool_use⟩
edit_section(id = "ch3", old = "Mlde", new = "Molde")

⟨tool_result⟩
OK. 1 replacement in ch3.

The structural design absorbed an invariant — sections keep their identity across edits; pages don't — behind the interface. But be honest about the price: Design B assumes a table of contents and section structure. Hand it a flat manuscript with no headings and it cannot work at all. It is a better language and a smaller one.

Name things by identity, not by position.
Positions move when the world changes; identities survive it.
(Pages, line numbers, row offsets — vs. sections, symbols, keys.)

Case 2 · The name is the policy

Two tool sets, and this time the difference is one word. The implementation behind both is byte-for-byte identical — the file goes to a recoverable store:

⟨tool_use⟩
remove_file(path = "notes_old.md")

⟨tool_use⟩
remove_file(path = "draft_v1.md")

⟨tool_use⟩
remove_file(path = "data_backup_2024.csv")

⟨tool_use⟩
archive_file(path = "notes_old.md")

The name is the policy.
A tool's name imports the model's priors about when, how eagerly,
and how carefully that kind of act is performed.

Case 3 · A specific tool is a frozen trajectory

The goal: monthly operations reports. Two languages:

⟨tool_use⟩
make_monthly_report(month = "2026-08")

⟨tool_result⟩
Report generated: august-2026.pdf

Design B says both requests — the August report takes eight steps instead of one (query, summarize, format, with more tokens and more places to err), and the Ålesund comparison takes ten. Slower on the anticipated path; alive on all the neighbors.

A specific tool is a frozen trajectory.
Buy one wherever you'll walk the same path often; keep composable
parts for the neighbors you haven't met yet.

Case 4 · Unknown, or unexamined?

The goal: an agent for a support inbox. The first design meeting says the fatal sentence — "requests could be anything" — and reaches for the universal word:

Then someone spends a week logging what actually arrives:

Cover the tail with a handoff, not with power.
"Anything can arrive" does not mean "the agent must do anything."
Enumerate the head; hand off the tail.

The four principles, one idea

1. Name things by identity, not by position.
2. The name is the policy.
3. A specific tool is a frozen trajectory.
4. Cover the tail with a handoff, not with power.

Every case is the same sentence wearing different clothes: the tools condition the trajectory before the LLM ever speaks. Design A and Design B never differed in what was possible for the underlying system — they differed in what the language made sayable, cheap, stable, and safe.