Tool Calls in the Real World

Study Guide · Chapter 2: Tool Calls · 6 min read

Every serious agent product is ultimately a well-designed set of tools. Here is how teams keep that toolset reliable as it grows from three functions to three hundred.

Payments, tickets, and other high-stakes calls

For anything that moves money or changes records, teams wrap tools in extra ceremony: dry-run modes, spending limits per actor, manager approval above a threshold, and immutable logs of every execution.

A useful rule of thumb: the cost of a mistaken call should decide how much ceremony it gets. Reading a calendar can be simple; issuing a refund should not be.

Evolving tools without breaking agents

Schemas are versioned like any public API. When a field changes meaning or a parameter is added, old payloads must still validate or fail with clear upgrade hints the model can act on.

A golden test harness — hundreds of known-good and deliberately malformed payloads — runs on every change so model upgrades and tool refactors never silently break each other.

Designing tools models use well

The best tools are narrow and descriptive: 'search_invoices_by_date_range' beats 'do_invoice_stuff'. Names, descriptions, and error messages are prompt engineering — the model reads them all.

Fewer, sharper tools consistently outperform a sprawling menu. If an agent keeps picking the wrong tool, the fix is usually clearer descriptions rather than a better model.

Key Points

Match ceremony to blast radius: read-only tools stay light, state-changing tools get guardrails.
Version schemas and run golden-payload tests on every release.
Tool names and descriptions are part of your prompt — write them for the model.
Prefer many small, focused tools over a few overloaded ones.

All study guides for this chapter: Tool Calls, Explained Simply · How Tool Calling Works Under the Hood · Tool Calls in the Real World