« Phase 02 README · Warmup · Deep Dive · Principal Deep Dive · Core Contributor · Staff Notes

Phase 02 — Hitchhiker's Guide

30-second mental model

The model emits a structured tool call {"name","arguments"}; your code validates the arguments against a JSON Schema before executing, and on failure returns a structured error and runs a repair loop — never crashes. Constrained decoding guarantees the JSON parses, not that it's correct. The tool schema is where the trust boundary (Phase 00) is enforced in code, and it's the authorization surface (Phase 10).

The facts to tattoo on your arm

FactWhy
validate before executebad call → structured error, no half-done side effect
collect all schema errorsthe repair loop fixes more with the full list
isinstance(True, int) is Truereject bools where integers are required
arguments may be a JSON stringjson.loads it twice
constrained ≠ correctgrammar guarantees syntax, not semantics
few sharp tools > many fuzzy onesfewer wrong choices → higher per-step reliability
bound the repair looprepairs cost tokens/latency; some calls can't be fixed

Framework one-liners

  • OpenAI / Anthropic tool use — pass tool schemas, get tool calls back; the wire format this phase reimplements.
  • Pydantic AI / instructor — declare a Pydantic model → JSON Schema → typed object out; §9 is what's underneath.
  • outlines / guidance / GBNF — constrained decoding: mask logits to a grammar so output parses by construction.
  • JSON mode / response_format — "always answer in this JSON shape," vs tool mode's "choose a tool."

War stories

  • The refund that fired on a string. amount: "5000" flowed into payment code with no schema check; a validator + repair loop would have caught it before the side effect.
  • The double-encoded arguments. A provider returned arguments as a JSON string; the parser assumed a dict and every call "failed validation" until someone added the second json.loads.
  • 40 tools, wrong pick every time. Consolidating to 8 well-described tools fixed the agent more than any prompt tweak.

Vocabulary

Tool/function call · JSON Schema (type/required/properties/enum/items/ additionalProperties) · validate-before-execute · repair loop · structured output · JSON mode vs tool mode vs constrained decoding · double-encoded arguments · parallel tool calls · idempotent tool.

Beginner mistakes

  1. Executing before validating (cryptic crash + half-done side effect).
  2. Assuming constrained decoding means the values are correct.
  3. isinstance(x, int) passing True.
  4. Treating arguments as always-a-dict.
  5. Dumping 40 overlapping tools on the model.
  6. Returning KeyError instead of a model-actionable error message.