The schema → call → result dance

Why tool calling matters

An LLM has no real-time data, can't run code, can't search the web, can't read your database. Tools fix all of that.

The protocol

Every API that supports tools (OpenAI, Anthropic, Google) does essentially the same thing:

1. You declare your tools with JSON schemas.
2. The model gets your prompt + the schemas.
3. The model either answers directly or emits a structured call.
4. You execute the call (in your code) and feed the result back.
5. Repeat until the model returns an answer instead of another call.

Try this — predict before you click

1. Pick the calculator scenario. Predict: the model emits a JSON call like {"tool": "calculator", "expression": "..."}, the runtime evaluates it, the model gets the result back, then formats a natural-language answer. Three round-trips: prompt → tool-call → tool-result → final answer.
2. Imagine the model produces a malformed JSON call (missing a field, wrong type). Predict: the runtime would either retry the call with a "parse error" message, or surface the error to the user. Production tool-using systems wrap the model's output in a JSON-schema validator before execution.
3. Imagine the tool itself errors (e.g., divide by zero, network timeout). Predict: the runtime returns the error as the tool result, and the model decides whether to retry, swap tools, or apologize. Try the agent trace viewer's failure-injection toggle to see this loop in a multi-step trace.
4. Compare scenarios. Predict: the same loop (prompt → call → result → answer) repeats regardless of which tool is invoked. The structure is what matters; the specific tool is interchangeable. This is why "tool use" is a protocol, not a feature.

Anchored to 11-agents/tool-use-and-function-calling. Code-side: /ship/09 — tools and function calling.