Context tools vs action tools

A shared interface for every tool commonly carries an explicit isWrite: boolean flag — sometimes expanded further into a riskTier (read / standard / high), since not all writes carry equal blast radius: recording an expense and voiding a payment are both "writes," but not remotely equivalent in how carefully they need to be gated.

A model deciding to call a tool is, fundamentally, a probabilistic judgment about what the conversation needs next — not a guarantee. For a context tool, a wrong or unnecessary call is nearly costless: it fetches information that turns out to be irrelevant, and the conversation continues. For an action tool, the same kind of mistake — calling it based on a misread instruction, a misunderstood confirmation, or an outright hallucinated intent — means something real happened that shouldn't have. The split exists specifically so that difference in consequence maps to a difference in how much scrutiny each category gets before anything actually executes.

This doesn't mean action tools can't be called by the model — it means calling them doesn't immediately do the real thing. Covered in full in the next lesson, but the shape of it: an action tool's execute function, when the model calls it, doesn't perform the mutation directly. It records what's proposed, and a completely separate, explicit confirmation step is what actually performs it — decoupling "the model decided this should happen" from "this actually happened."

The test isn't "does this tool use a database" — a context tool reading from a database is still read-only and still safe to auto-execute. The test is: does calling this tool change anything a human would care about being changed without their explicit awareness? A tool that looks up a customer's order history is a context tool even though it hits the database. A tool that cancels that order is an action tool even if, mechanically, it's also "just a database call." The distinction is about consequence, not implementation detail.

Even within "action tools," some carry meaningfully more risk than others — voiding a completed payment, issuing a bulk notification to every user, changing someone's account role. Real systems commonly give these a stronger, more explicit confirmation step than an ordinary create-a-record action — not because the underlying mechanism is different, but because the cost of getting it wrong is categorically higher, and the UI/UX around confirming it should reflect that difference rather than treating every write identically.

Once an agent has structured UI in front of it — buttons, a tappable list, a time-slot picker — it's tempting to wire the tap straight to the action it obviously corresponds to, bypassing the model entirely: the user tapped "3pm," so just go call the booking tool with 3pm directly. This looks like an optimization and quietly reintroduces everything the context/action split was built to prevent — the tap now triggers a write with no model reasoning over it at all, no chance to notice the slot conflicts with something already discussed earlier in the conversation, no propose-then-confirm gate in between.

The alternative that keeps the model in the loop: feed the tap back in as an ordinary conversational turn — "the user selected 3pm" — through the exact same message-handling path a typed reply takes. The model sees it in context, decides whether to call the action tool (with the surrounding conversation still informing that decision), and the normal action-tool machinery — proposal, confirmation, everything covered above — runs unchanged. The button didn't create a new code path; it just produced a different kind of input into the one path that already existed.

Some operations shouldn't be reachable by an agent through any tool, at any risk tier — authentication flows, billing/payment-gateway webhook handling, and database migrations are common examples of things kept entirely outside an agent's tool surface, not gated-but-available. Some blast radii are large enough that "carefully confirmed" still isn't the right answer; "not exposed to the model at all" is.