Jev takes a state and a questions map. Everything a question can see has to be in the state or in the question itself. That makes the instructions a first-class part of the interface, not a string you build at the last minute. The advanced structure guide shows how far this goes: instructions, option descriptions, score levels, and Noul criteria all accept JSON, so you can label question parts, pass schemas and taxonomies, and keep candidate paths alive.
The practical benefit is auditability. A structured question can be diffed, versioned, and tested. A prompt assembled from three f-strings cannot.
Instructions are data
The primitives guide describes the basic shape: a question has instructions, and depending on the primitive it may also have criteria, options, score levels, or a legend. The advanced guide adds that every field is an entry type: string, object, array, or null. That means you can pass a schema as the criteria for a Noul, or a taxonomy subtree as the options for a Choice.
The reason to do this is not elegance. It is that the model reads the structure literally. If the instructions say “use ticket.messages[0].text,” the model knows which field you mean. If the state has three messages and the instructions say “the message,” the model has to guess. The state design guide makes the same recommendation: name the part you are asking about with a backticked path.
Reference state fields explicitly
Backtick references are the simplest form of structured instruction. The advanced guide recommends referencing state fields by key name, such as potential_duplicate, so the model does not have to infer which field the question is about. This is especially important when a state contains several similar objects: two addresses, three prices, a list of line items.
The pre-parsed extraction cookbook takes the idea further. Regex finds candidate spans; Jev picks the requested one. The instructions do not ask the model to find an email in free text; they ask it to choose among spans that code already found. The returned value is copied verbatim, so it cannot be invented. The cookbook's caveat is that Choice caps at 255 options, and candidates without a regex need a roster, NER, or an LLM.
Define what each option is and is not
The advanced guide allows option descriptions with fields like covers, not_for, and examples. That is the right place to resolve near-misses. A label called billing_issue is ambiguous on its own; a description that says “covers charges, invoices, and refunds; not for login or access problems” is a policy statement the model can read.
The IIA study is a warning here. Adding options changes the probability of the correct label even when the new option is not the answer. A detailed description does not make the option set neutral, but it does make the intended boundary explicit. Pair descriptions with a test set that includes near-misses and off-domain options.
Use structured criteria for policy
Noul criteria can be a JSON object rather than a sentence. That lets you express a policy as a set of fields: thresholds, exceptions, definitions, and examples. The model still reads it, so it is not a formal specification, but it is more consistent than prose and easier to diff.
The jaggedness notes recommend keeping criteria literal. Do not rely on the model to infer that a policy window excludes weekends, or that a “business day” means something specific. Put the rule in the criteria or compute it in code. The contradictory criteria article covers precedence; structured criteria make that precedence visible.
Images and boxes are references too
The image assets docs describe a top-level assets map keyed by reference string. The reference can be placed anywhere in state, instructions, or criteria, and the API swaps each reference for the image. That is the same pattern as a backticked state field: the question names the object, and the runtime resolves it.
Box questions go one step further. The instructions describe what to find and in which image, and the answer is four edges as fractions of the image plus a confidence. Box takes no criteria field and has no not-found value, so the docs recommend pairing it with a Noul that checks whether the target is present. That pairing is a structured instruction in practice: one question locates, another verifies.
The visual grounding article covers the image side in more detail.
Keep the structure small enough to read
The advanced guide's main caveat is size. Taxonomy subtrees grow fast, and untrimmed branches inflate the input bill. The recommendation is to pass a subtree per option and trim each branch to its direct children plus a sample of leaves. The same discipline applies to criteria: include the fields the question actually needs, not the whole policy document.
The parallel-questions cookbook shows why this matters. One batched request over a ~54,000-character document was 12.2x cheaper and 10x faster than 13 separate calls, but the state was still bounded. Structure does not remove the token budget; it makes the budget visible.
A short checklist
- Pass instructions as structured data, not a string-built prompt.
- Reference state fields by backticked key name.
- Give each option a
covers,not_for, and example description when labels are close. - Put policy thresholds and exceptions in criteria, not in prose.
- Use asset references for images and a presence Noul for boxes.
- Trim taxonomies to the subtree the request needs.
- Version the structured question alongside the model.
Structured instructions are not a formatting preference. They are the difference between a question you can test and a question you can only hope behaves the same way twice.