Implement #5: Implementing Tools and Function Calling

[yagop]

Closes #5

Chapter 5 teaches the core tool-use round-trip of the Messages API: declaring a tool, catching the tool_use block, executing it, returning a tool_result, dispatching to typed handlers, reporting errors with is_error, and steering with tool_choice. Authored by the write-chapter ultracode Workflow (1 doc agent + 5 implement/review pipeline pairs), then verified end-to-end.

Definition of done

• Chapter at chapters/05-tools.md, <=120 lines, <=4 main-line H2s plus a closer
• Every sample runnable with bun run, imported via <<< @/examples/05-tools/file.ts
• One-home rule held; reader addressed as "you"; intro + sections open warm
• Samples use only real @anthropic-ai/sdk surface (verified against the SDK .d.ts and current docs); ASCII punctuation only
• Optional material in asides (a warning, an info table, one ASCII diagram); main line complete without them
• Linked from README.md and the .vitepress/config.ts sidebar; bun x vitepress build passes
• Sample line budget: see note below - samples are 36-78 lines, above the issue's stated <=35, because the skill's code budget was raised to a 100-line hard cap (verbose-preferred) in a prior change

Verification (run live against an Anthropic-compatible gateway)

Chapter budget: wc -l -> 68 (<=120); grep -c '^## ' -> 4.

Samples (all <=100 lines, comment:code <=0.40, one statement per line):

define-tool.ts        45 lines  ratio 0.156
single-tool-loop.ts   49 lines  ratio 0.086
dispatch-handlers.ts  78 lines  ratio 0.119
tool-errors.ts        68 lines  ratio 0.078
tool-choice.ts        44 lines  ratio 0.057

bunx tsc --noEmit clean; bun x vitepress@2.0.0-alpha.17 build passes (all five snippets resolve). Each sample was run, not just typechecked:

• define-tool.ts -> stop_reason: tool_use, then the tool_use block's id, name, and the already-parsed input object ({ location: "Tokyo, Japan" }) - no JSON.parse.
• single-tool-loop.ts -> full round-trip, final answer: "The current weather in Madrid is 21C and sunny..."
• dispatch-handlers.ts -> both tools dispatched: weather + 19 + 23 = 42.
• tool-errors.ts -> error: denominator was 0... then ok: 3; the model recovers and reports both.
• tool-choice.ts -> ran all four modes (auto, any, { type: 'tool' }, auto + disable_parallel_tool_use); each returned stop_reason=tool_use chose=get_weather.

Notes / honesty flags

• tool_choice on this gateway: the weather prompt elicits the tool in every mode (true on Anthropic direct too), so the live output is uniform - the modes only diverge on a prompt the model could answer in text. I adjusted the chapter prose to say exactly that rather than overpromise a "shift." Separately, I confirmed by probe that this GLM gateway does not honor forced tool_choice ({ type: 'tool' } on an unrelated prompt returns end_turn, no tool_use); the sample code is correct against the Anthropic API.
• dispatch-handlers.ts: the Workflow emitted Record<string, Handler> (an index-signature type); I converted it to Map<string, Handler> to honor the "no index signatures" convention. Re-ran + tsc clean after.
• Sample sizes vs the issue's <=35: the skill's code budget was raised to a 100-line hard cap (verbose-preferred) in a prior change, so these run 36-78 lines. If you want the issue DoD reconciled, the <=35 line is the place.

Review flags

None - the Workflow returned all five samples as fully compliant (no flagged files).

🤖 Generated with Claude Code