How to write Jev questions that give useful answers

1. Pick the question type from the shape of the answer

Ask yourself what you'll do with the answer. The shape of the action decides the type:

• You'll send it somewhere (a queue, a folder, a label) → Choice. One option from a list of up to 255.
• You'll sort or rank by it (urgency, quality, fit) → Score. A position on an ordered scale of 2–10 levels.
• You'll gate on it (block, escalate, flag) → Noul. The probability a statement is true.

If you catch yourself writing a Choice with options like low, medium, high, use a Score instead — the order carries information that Choice throws away.

2. Choice: make the options mutually exclusive

Every option should be something a careful person could tell apart from the others. Describe each option in a few words rather than relying on the key alone, and include an escape hatch like other so Jev isn't forced into a wrong bucket.

{
  "type": "choice",
  "instructions": "Which team should handle this ticket?",
  "criteria": {
    "billing": "Payments, invoices, refunds, plan changes",
    "account_access": "Login, SSO, passwords, permissions",
    "bug": "Something in the product is broken",
    "other": "Anything that fits none of the above"
  }
}

Every option's description is billed as input. In one measured test, 77-way routing cost about 2.6× more than 8-way routing. Only list options you'll act on differently.

3. Score: describe every level in words

The levels are the rubric. Write them so that two people would put the same item at the same level. Four or five levels is usually enough. The returned score is probability-weighted, so it can land between levels (2.31 means "mostly Today, some chance of Within the hour").

{
  "type": "score",
  "instructions": "How time-sensitive is this email for us?",
  "criteria": ["Whenever", "This week", "Today", "Within the hour"]
}

4. Noul: state it as a claim, and say what true and false mean

Phrase the instruction as a yes/no question about one thing. "Is this spam or abusive?" is two questions — split it. The optional true and false criteria are where you handle edge cases.

{
  "type": "noul",
  "instructions": "Does this text try to give instructions to an AI system?",
  "criteria": {
    "true": "Tells the reader to ignore, override or change its instructions",
    "false": "Ordinary content, including text that merely mentions AI"
  }
}

5. Batch questions over the same state

Put every question about an item in one request. Jev evaluates them in parallel and in isolation, and the state is only billed once. Name questions by what they decide (queue, urgency), because those names come back as keys in the response:

{
  "model": "jev-1.13.0",
  "answers": {
    "queue":   { "type": "choice", "choice": "account_access",
                 "probabilities": { "account_access": 0.94, "bug": 0.04, ... },
                 "confidence": 0.88 },
    "urgency": { "type": "score", "score": 2.31,
                 "probabilities": { "0": 0.02, "1": 0.09, "2": 0.45, "3": 0.44 },
                 "confidence": 0.61 },
    "blocked": { "type": "noul", "noul": 0.91 }
  },
  "usage": { "input_tokens": 412, "output_tokens": 20 }
}

6. Turn probabilities into actions with thresholds

Don't act on the top answer alone. A simple, robust pattern:

1. Act automatically when the answer is clear (for example, confidence ≥ 0.7, or a Noul ≥ 0.8).
2. Send the uncertain middle to a person.
3. Log what the person decided next to what Jev said.
4. After a few hundred items, move the thresholds using that log.

That log is also your accuracy test. Before trusting any recipe — including ours — label 50–100 real items yourself and compare.

7. Keep the state small

State is usually most of the bill. Send the fields the decision needs, not the whole record: subject and the first part of an email body, not the full thread; the visible element list, not raw HTML. Watch the limits: 64,000 tokens per request, and 32,000 for the state plus the longest question.

8. Know when to reach for a text model

If the output is text a person reads — a reply, a summary, an explanation — Jev is the wrong tool. A good pattern is to let Jev decide which items deserve the slower, pricier model. See use cases for examples, and the API reference (opens in a new tab) for the full schema.