Tools and Structured Outputs

Key jargon

Term	Plain-language meaning
Tool schema	A machine-readable contract describing an operation and its arguments.
Structured output	Model output constrained to a defined data shape such as JSON Schema.
Validation	Checking types, ranges, formats, and invariants before data is used.
Tool result	The trusted application's report of what happened after execution.

Key concepts

A model emits a candidate tool request; it does not execute the tool by merely naming it.
Schema validity is necessary but does not establish authorization or business correctness.

Concept map

flowchart LR
    A["Model proposes structured call"] --> B["Validate schema"]
    B --> C["Authorize and execute"]
    C --> D["Return observed result"]

A tool definition is an interface contract, not permission. The model may propose a call; the harness authenticates, authorizes, validates, executes, and records it.

Tool contract

Field	Purpose
Name and description	Make intended use unambiguous
Input schema	Constrain arguments and types
Identity	Bind user, tenant, and workload
Authorization	Check this action on this resource now
Side-effect class	Read, create, update, delete, communicate, purchase
Idempotency/effect key	Prevent accidental duplicate effects
Timeout and error model	Support predictable recovery
Output schema	Separate trusted result from display text

Validate model-produced JSON with a real schema. Then validate business semantics: a syntactically valid transfer or deletion can still be unauthorized.

Exercise

Design a read-only lookup_order tool. Include allowed fields, tenant binding, timeout, error codes, logging, and data minimization.