State is the material Jev evaluates. It may be a text string or structured JSON containing text and related context. Questions describe the judgments to make about that state. The official state guide recommends a named object for most requests because the relationship between fields stays clear.

Start from the action

Write the action your code might take, then work backwards to the smallest judgment that informs it. For a refund review queue, the state might contain the customer message, charge records, and relevant policy text. A Noul could ask whether the message requests a refund. Another question could check whether the policy text describes a duplicate-charge exception. Your code still verifies the actual charges and decides whether a refund may be issued.

Keep relevant facts together

Give fields descriptive names and include only the context needed for the question. For example:

{"ticket":{"message":"I was charged twice for order A-104."},"policy":"Duplicate charges are eligible for review."}

Use a plain string when there is only one piece of text. Use an object when relationships matter. The current documentation says Jev accepts text-based state; do not assume that passing an image or audio file will work. Avoid collecting sensitive data merely because the API accepts a large object.

Write atomic questions

Ask “Does the message request a refund?” rather than “Should we issue a refund, prioritize the customer, and notify billing?” The latter hides several decisions with different evidence and consequences. Separate them, then combine results in code. Define Choice criteria so neighboring options have a meaningful boundary, and define Score levels in observable language.

Test the boundaries

Build a small evaluation set: clear positives, clear negatives, missing information, contradictions, and confusing wording. Check whether each question is answerable from the supplied state. Remove irrelevant material if results deteriorate. The jev-1.13 limitations identify literal reading, indirection, and excessive irrelevant state as possible failure modes. Keep arithmetic, date ordering, and permissions in deterministic code.

The agent-memory example makes the state boundary concrete: the original conversation and proposed memory both matter to the support check. The Postgres classifier instead uses SQL and schema context to prioritize which query shapes deserve closer investigation; it does not execute the queries to decide.

After the question works, decide when to ask for human review. For more design examples, see How to build with TypeSafe.