Six types. Every type names its answer: choice (one of your labels), score (a level on your scale), truth (a probability), number (a value on your grid), point (a spot in your image), box (a rectangle around the thing).
| Type | Goal | What comes back |
|---|---|---|
Choice choice | Pick one option from the list you give | choice (always one of your keys), probabilities per option, confidence |
Score score | Place the input on your ordered scale or rubric | score (expected level, for example 2.31 of 0 to 3), probabilities per level, legend, confidence |
Truth truth | Is this statement true? | truth, one probability from 0.00 to 1.00 that the statement is true |
Number number | How many, or what value? | number (a value on your grid), expected, confidence, probabilities per value |
Point point | Where is it? | x, y (one spot in the image), present, confidence, image, width, height |
Box box | Where is it, and how far does it reach? | x1, y1, x2, y2 (a rectangle around the thing), present, confidence, image, width, height |
The questions map#
questions is an object. Its keys are your names for the questions, and the answers come back under the same keys. Use short, stable names your code can read, such as route or refund. The keys are labels for your code: the model never sees them, so each question must carry its full meaning in its instructions and criteria.
- Any string is a key. Spaces, punctuation, dots, numeric strings such as
01and the empty string all work:same_as_record_18,plot_price.style?and__overall__::judgeare valid keys. - Keys come back byte for byte. No trimming, no case folding, no reordering of characters, so
Routewith a trailing space is answered asRoute. - No length limit of their own. A key is bounded only by the body size. Option names are bounded by the token limit, since the model reads them.
- No count limit. A request may hold as many questions as its tokens allow: 300 short questions about a short state are answered in one call.
- Order inside a question does not matter.
type,instructionsandcriteriacan come in any order.
{
"questions": {
"route": {
"type": "choice",
"instructions": "Where should this go?",
"criteria": { "billing": "money", "bug": "broken", "account": "login" }
},
"urgency": {
"type": "score",
"instructions": "How urgent is this?",
"criteria": ["routine", "today", "urgent", "critical"]
},
"refund": {
"type": "truth",
"instructions": "Refund this automatically?"
}
}
}Question fields#
type"choice" | "score" | "truth" | "number" | "point" | "box"required- Fixes the answer's shape: choice, score, truth, number, point or box. Point and box answer where in an image; see Points and boxes.
instructionsstring | object | array- What to decide, in plain words, almost always worth one sentence. A string is the usual form; an object or an array can carry the question with the data it refers to (see Structured instructions). A choice, a score and a number can leave it out and are answered from their options, levels or grid alone. A truth question needs
instructionsorcriteria: with neither, it is refused with a400. criteriaobject | array- Choice: an object of option names to what each option means (1 to 255), required; an empty object is a
400. Score: an array of levels from lowest to highest (up to 10), required. Truth: optional{ "true": "...", "false": "..." }describing what true and false mean. Number: not used. The pages of each type list the forms a description may take. min, max, stepnumber- Number only: the grid of values the answer can take. Default 0 to 255, step 1; steps such as 0.5 and 0.1 work too. Up to 256 values are one question, and finer or wider grids are composed in the same call, up to 4,096 values in all. See Number.
Writing questions that work#
- Ask one thing. "Is this urgent and about billing?" is two questions. Split it and you get two calibrated answers.
- Describe every option.
"bug": "something is broken"beats a bare key. The description is what the model compares against. - Cover the space. If an input can fit none of your options, add one for that, such as
"other": "none of these". A choice always returns one of your keys. - Order scales from low to high. Score levels are indexed from 0 in the order you send them, and the expected score depends on that order.
- Phrase a Truth question as a statement that can be true. "Does the receipt show the same total as the claim?" reads better than "check the receipt".
- Give a number question the range it can really take. "How many cars are visible?" on 0 to 50 for a ten-bay row, not the default 0 to 255. A tight grid puts the probability where it belongs.
Better answers: give it the facts and the rule#
A question alone is a complete request: it is answered from its own words. But then the model can only guess what you mean. Put the facts in a JSON state and say in criteria what true and false mean, and the answer follows your rule instead of a guess.
{
"questions": {
"is_sandwich": {
"type": "truth",
"instructions": "Is hotdog a sandwich?"
}
}
}| Request | DecisionNode Flash | DecisionNode | Input tokens |
|---|---|---|---|
| Plain: "Is hotdog a sandwich?" | 0.94 | 0.52 | 19 |
| A split bun counts | 0.97 | 0.83 | 137 |
| Only two slices count | 0.33 | 0.02 | 145 |
Asked plain, the two models guess differently: 0.94 and 0.52. Given the facts and a rule, both follow the rule: a split bun that counts as bread makes it a sandwich, and a rule of two separate slices makes it not one. On DecisionNode Flash the stricter rule brings the answer down to 0.33, not all the way: the answer moves toward the rule you state, so state it.
- The state carries the facts: here, what a hot dog is, so the model reads the thing you mean instead of recalling one.
- The criteria say what true and false mean, so the answer applies your rule, not the model's idea of the word.
- Instructions can point at a state field in backticks: "Is
fooda sandwich?" asks about exactly the fact infood.
How to write it#
- 1.Put the facts in a JSON state, as named fields.
- 2.Say in
criteriawhat true and false mean, or what each option or level means. - 3.Refer to state fields in backticks, such as
foodorclaimed_total. - 4.Ask one decision per question.
In the playground examples#
The same holds across the playground's examples. Each was asked plain, as a short sentence with no criteria, and with its state and criteria, on DecisionNode Flash, the model a playground run uses, the median of 3. Open one in the playground and choose Compare with a plain question under Run to see both answers side by side.
| Example | Question | Plain | With state and criteria |
|---|---|---|---|
| Name the commit | kind | fix 0.57 | fix 0.71 |
| Traffic | queue | 6 at 0.35 | 6 at 0.63 |
congestion | jammed 0.63 | slow 0.43 (the intended answer) | |
wrong_way | 0.75 | 0.16 (the intended answer is no) | |
| People count | people | 0 at 0.52 | 25 at 0.14 (23 are there) |
crowding | busy 0.53 | busy 0.53 | |
exit_blocked | 0.31 | 0.00 (the intended answer is no) | |
| Sorter | lane | lane_1 0.99 | lane_2 1.00 (the intended lane) |
damaged | 0.17 | 0.01 | |
label_readable | 0.04 | 0.98 | |
| Agent guardrail | verdict | block 0.73 | block 0.82 |
risk | destructive 0.79 | destructive 0.85 | |
in_scope | 0.18 | 0.05 | |
| Receipt check | total_matches | 0.44 | 1.00 |
date_matches | 1.00 | 1.00 | |
currency | SEK 0.82 | SEK 1.00 | |
legible | fully readable 0.99 | fully readable 1.00 | |
alcohol | 0.92 | 0.99 | |
| Age gate | adult | 0.01 | 0.00 |
matches_stated | 0.88 | 0.11 (the intended answer is no) | |
age_band | under_13 1.00 | under_13 1.00 |
Choice: name the commit. The criteria say what each kind of commit means, so the message is compared with a definition, not a word.
{
"state": "Stop skipping the last page when the cursor lands on an exact multiple of the page size. Adds a regression test for 100 items at 25 per page.",
"questions": {
"kind": {
"type": "choice",
"instructions": "What kind of commit is this?",
"criteria": {
"feat": "",
"fix": "",
"refactor": "",
"docs": "",
"chore": ""
}
}
}
}Junction camera that times its own signals. The state says which lane is which and which way each one faces; the criteria say what facing the wrong way is.
{
"images": [
{ "id": "frame", "media_type": "image/jpeg", "data": "<base64>" }
],
"questions": {
"queue": {
"type": "number",
"instructions": "How many cars are waiting?",
"min": 0,
"max": 40
},
"congestion": {
"type": "score",
"instructions": "How bad is the traffic?",
"criteria": ["free flowing", "busy", "slow", "jammed"]
},
"wrong_way": {
"type": "truth",
"instructions": "Is anyone going the wrong way?"
}
}
}Concourse camera that opens the next gate. The state gives the area's capacity, and the instructions name the marked waiting area and the hatched exit lane.
{
"images": [
{ "id": "frame", "media_type": "image/jpeg", "data": "<base64>" }
],
"questions": {
"people": {
"type": "number",
"instructions": "How many people are there?",
"min": 0,
"max": 80
},
"crowding": {
"type": "score",
"instructions": "How crowded is it?",
"criteria": ["empty", "comfortable", "busy", "crowded", "unsafe"]
},
"exit_blocked": {
"type": "truth",
"instructions": "Is the exit blocked?"
}
}
}Sorter that sends every package to its lane. The state carries the line's sorting rule; the criteria say what each lane takes, what counts as damage and when a label is readable.
{
"images": [
{ "id": "frame", "media_type": "image/jpeg", "data": "<base64>" }
],
"questions": {
"lane": {
"type": "choice",
"instructions": "Which lane?",
"criteria": { "lane_1": "", "lane_2": "", "rework": "" }
},
"damaged": { "type": "truth", "instructions": "Is it damaged?" },
"label_readable": {
"type": "truth",
"instructions": "Can the label be read?"
}
}
}Guardrail for agent tool calls. The state keeps the user's task apart from the proposed call; the criteria say when to run, send back or block.
{
"state": "The agent wants to run rm -rf ./ && git push --force origin main to clear the build cache.",
"questions": {
"verdict": {
"type": "choice",
"instructions": "Should the agent run this?",
"criteria": { "run": "", "replan": "", "block": "" }
},
"risk": {
"type": "score",
"instructions": "How risky is it?",
"criteria": ["harmless", "easy to undo", "hard to undo", "destructive"]
},
"in_scope": {
"type": "truth",
"instructions": "Is this command needed?"
}
}
}Receipt and invoice checker. The state carries the claim's fields; the criteria say how a Swedish receipt writes 1315.50.
{
"state": "Expense claim: 1315.50 SEK at Hallon Bistro on 2026-09-28.",
"images": [
{ "id": "receipt", "media_type": "image/jpeg", "data": "<base64>" }
],
"questions": {
"total_matches": {
"type": "truth",
"instructions": "Does the total match?"
},
"date_matches": {
"type": "truth",
"instructions": "Does the date match?"
},
"currency": {
"type": "choice",
"instructions": "What currency is it?",
"criteria": { "SEK": "", "NOK": "", "EUR": "", "USD": "" }
},
"legible": {
"type": "score",
"instructions": "Is it readable?",
"criteria": ["unreadable", "partly readable", "fully readable"]
},
"alcohol": { "type": "truth", "instructions": "Any alcohol?" }
}
}Age gate on a sign-up selfie. The state gives the minimum age and the stated birth year; the criteria say what fits them.
{
"state": "Account birth year 2004.",
"images": [
{ "id": "selfie", "media_type": "image/jpeg", "data": "<base64>" }
],
"boosters": ["age"],
"questions": {
"adult": { "type": "truth", "instructions": "Is this person an adult?" },
"matches_stated": {
"type": "truth",
"instructions": "Does this match the birth year?"
},
"age_band": {
"type": "choice",
"instructions": "How old are they?",
"criteria": {
"under_13": "",
"teen": "",
"young_adult": "",
"adult": ""
}
}
}
}Structured instructions#
instructions can be an object or an array instead of a string. Put the question in one field and the data it refers to in others. The field names are yours (none is reserved), and the model reads the names together with the values, so name them for what they hold. Data fields may be empty: "", null or []. An object or array is read as compact JSON, the same way as the state.
{
"duplicate": {
"type": "truth",
"instructions": {
"question": "Is `potential_duplicate` the same order as `ticket.order`?",
"potential_duplicate": {
"id": "A-1182",
"total": "49.00",
"placed": "2026-10-04"
},
"note": "Treat a different currency as a different order."
}
}
}- References are read, not resolved. A state key written in backticks (
ticket_message), a dot-and-index path (ticket.messages[0].text) or the name of a sibling field reaches the model exactly as written, and the model reads it. The server does not look anything up or substitute values. - Any phrasing works. A question ("Does this message express urgency?"), a statement to judge ("The customer asks for a refund"), a noun phrase ("How frustrated the customer appears") or an imperative ("Determine the category of this ticket").
- References work inside
criteriatoo, for example an option described as the amount inclaim.total.
How questions are answered#
- Independently. An answer does not depend on which other questions are in the request or on their order. Ten questions in one request get the same answers as ten requests with one question each, for the state's tokens once.
- Without chaining. One answer is never input to another. When a decision depends on an earlier answer, send a second request built from the first answer.
- Every time, with what there is. With little evidence, or no state, a question is still answered: a choice or a score gets a spread distribution with low confidence, a truth a value near 0.50. That is an answer, not an error, and your threshold treats it as unsure.
- Even when the premise does not hold. A question that does not apply to the state, such as the severity of a bug on a billing ticket, still gets a complete, valid answer and does not disturb the others.
- With one of your options. A choice always picks one of your keys, even when none fits. Add an option such as
"other": "none of these"when that can happen. - All or nothing. A request succeeds for every question or fails as a whole. There are no partial answers. See Errors.