Best practices

Lessons measured on real requests. Most mistakes come from how a schema asks, not from the API.

Design the schema

• One fact per field. Split "name and ID" into two fields.
• Use the most specific type. enum instead of free text for categories, bool for yes/no, number with integer: true for amounts.
• Use extract: true for anything copied from the input: names, IDs, reference numbers. It makes invented or re-spelled values impossible.
• Use enum for values you pass on (for example to a URL). An extract field asked for "the asset the user means" returned the whole sentence, which is a valid part of the text.
• Size numbers for their range. max_digits counts every character; money usually needs 10–12.

Write instructions

• Say what the value is, name the traps (subtotal vs total, PB1 is a tax), and define when it is null.
• Give an example for odd formats: "(56rb = 56000)".
• Put shared rules in system.
• For decisions, define each option in the instruction. Without definitions, a model chose "reject" for a case the policy said to review, confidently and unanimously.

Let code do what code does best

Task	Do	Avoid
Arithmetic	compute fields	asking the model to calculate
Consistency	*_expr rules	asking the model "is the total correct?"
Formats and lengths	len_*, match rules	asking the model to count
Status, balances, approvals	tool calls to the system of record	reading them from the conversation
Formatting big numbers	your own code	"write with thousands separators" (1514071277 became "Rp15.140.712.77")

Rules and stages

• Put gates after the data you want to keep: a reject cancels its own stage.
• Hide gate values from later prompts with a final {"do": "drop"}.
• Send low confidence straight to review; a return makes the model repeat its answer with more confidence.
• For data an answer depends on (a price, a balance), use on_error: "reject" on the call and an honest on_reject on the answer. With review only, a failed call led to an invented price.

Trust, but verify

• Treat needs_review as part of your workflow, not as an error.
• Pick review_threshold from an evaluation, and remember that confidence does not catch confident mistakes.
• Store provenance with each result you act on.
• In regulated decisions (credit, claims), use the result as a recommendation for a person.

Limits to plan for

• One request is processed at a time per deployment; set client timeouts in minutes and avoid very large max_new_tokens unless needed.
• max_new_tokens is per field (1–512). A cut-off typed value becomes null; a cut-off text is returned as far as it got.
• Enums: up to 24 values. Lists: simple values only.
• Very long documents are limited by the model's context length.
• Image input needs a vision model on the deployment.