Skip to content

Learning: Tool Calling + Structured Outputs

How to Use This Page

  • Treat schemas as contracts, not suggestions.
  • Validate every tool payload before execution.
  • Keep an error log for malformed calls.

Lesson 1: Fundamentals

Learn schema-first tool definitions and deterministic execution boundaries.

What You Learn

  • How to define strict argument contracts
  • Why stable tool names and keys matter
  • How to separate selection from execution

Walkthrough

  1. Define one tool schema with required fields.
  2. Ask the model for tool arguments in structured form.
  3. Parse and validate before running the tool.

Try It Yourself

  • Add one invalid field and verify validation catches it.
  • Change a required type and test schema rejection.
  • Return a clear error envelope when validation fails.

Lesson 2: Intermediate Patterns

Learn repair loops and controlled retries for malformed payloads.

What You Learn

  • How bounded repair retries improve success rate
  • Why unknown-field handling needs explicit policy
  • How response envelopes simplify downstream logic

Walkthrough

  1. Implement a validation -> repair -> revalidate cycle.
  2. Stop after a fixed retry count.
  3. Normalize success and failure outputs into one structure.

Try It Yourself

  • Create 5 malformed payload cases and test repair outcomes.
  • Compare strict reject vs lenient normalize behavior.
  • Log top validation errors to guide prompt improvements.

Lesson 3: Production Patterns

Learn policy gating and safe fallback strategies for risky tools.

What You Learn

  • How allowlists prevent unsafe tool execution
  • Why confidence-aware fallback improves safety
  • Which metrics indicate schema or prompt drift

Walkthrough

  1. Add an allowlist check before execution.
  2. Add fallback behavior for low-confidence or repeated failures.
  3. Track validation error rate and repair success rate.

Try It Yourself

  • Simulate a disallowed tool call and verify deterministic block behavior.
  • Run a batch test and compute success/repair/block percentages.
  • Propose one schema change based on observed error patterns.

Code Examples

  • Starter script: docs/starter/stage03_tool_calling.py
  • Stage architecture notes: docs/roadmap/stage-03-structured-tool-calling/architecture.md