Predicate vs choice vs score: choosing the right decision type

The Decisions API has three question types. They look interchangeable, since you can phrase almost any decision as any of them, but each returns different information, and picking the wrong one hides the part of the answer you need.

Predicate: is this true?

{
  type: "predicate",
  name: "duplicate_charge",
  instructions: "The customer reports being charged more than once.",
}
// → { type: "predicate", name: "duplicate_charge", probability: 0.97 }

A predicate returns one number: the estimated probability that the condition holds. There is no separate confidence field, because the probability already says how sure the model is. A value of 0.97 is strong support for yes, 0.03 is strong support for no, and 0.5 is the model telling you it can’t tell.

That symmetry is the reason to prefer predicates for yes/no decisions. You can set one bar for acting on “yes” and a different bar for acting on “no”, which matters whenever the two mistakes cost different amounts.

Write the instruction as a statement or a closed question about one thing. “The customer is angry and wants a refund” is two conditions; split it.

Choice: which one of these?

{
  type: "choice",
  name: "team",
  instructions: "Which team should own this customer message?",
  choices: [
    { value: "sales", description: "New purchases, pricing, demos, and quotes." },
    { value: "support", description: "Troubleshooting and technical problems." },
    { value: "billing", description: "Invoices, payments, and refunds." },
    { value: "other", description: "Anything that fits none of the above." },
  ],
}
// → { type: "choice", choice: "billing", confidence: 0.88, probabilities: [...] }

A choice returns exactly one of the values you supplied, a confidence value, and a probability for each option. Use it when the options are mutually exclusive and have no natural order.

Two habits make choices more reliable:

• Describe every option. Give every option a distinct value and a description of when it fits. A bare label like "support" leaves the boundary with "billing" to the model.
• Include a catch-all. Without an "other" option, a message that fits nothing still gets assigned somewhere, and the probabilities are spread over options that are all wrong.

Read the full distribution, not just the winner. A choice of billing at 0.51 with support at 0.47 is a different situation from billing at 0.95, even though the selected value is the same.

Score: where on this scale?

{
  type: "score",
  name: "urgency",
  instructions: "How urgent is this support ticket?",
  levels: [
    { label: "Low", description: "No time pressure." },
    { label: "Normal", description: "A real problem with a workaround." },
    { label: "High", description: "Blocks an important workflow." },
    { label: "Critical", description: "Outage or data loss affecting many users." },
  ],
}
// → { type: "score", score: 2.6, confidence: 0.71, probabilities: [...] }

A score places the input on levels you define, ordered from lowest to highest. The score field is the probability-weighted average of the level positions, counting from zero. With four levels the score runs from 0 to 3, and 2.6 means “between High and Critical, closer to Critical”.

That averaging is useful and also the main trap. The same score can come from very different beliefs:

The first ticket is a routine one. The second needs someone to look at it now, because there is an even chance it is an outage. If the top level triggers something expensive, such as paging an engineer, act on that level’s probability rather than on the averaged score.

Common mistakes

A two-option choice for a yes/no question

choices: [{ value: "approve" }, { value: "deny" }] works, but a predicate is simpler to threshold and makes the 0.5 “don’t know” region obvious. Use a choice only if there is a genuine third option, such as "needs_more_information".

A choice for something that can have several answers

A message can be both a bug report and a billing complaint. A choice will return one. Ask independent predicates instead:

questions: [
  { type: "predicate", name: "is_bug", instructions: "The message reports a defect." },
  { type: "predicate", name: "is_feature_request", instructions: "The message asks for a new capability." },
  { type: "predicate", name: "is_billing", instructions: "The message concerns a charge or invoice." },
]

A score for a category

Scoring “which product area” from 0 to 5 produces an average of categories, which means nothing. If the levels have no order, it is a choice.

Too many options

Every added option creates new boundaries the model must hold. If you need thirty categories, consider two steps: a coarse choice first, then a finer choice within the selected group.

Combining types in one request

The types are designed to be mixed. A single request can ask which team should own a ticket (choice), how urgent it is (score), and whether it mentions a legal threat (predicate), all against the same input. Each answer comes back in its own shape, in the order you asked. See the tutorial for the mechanics, and the AI decision routing guide for turning several answers into one action.

Related

• Ticket urgency template: a score with a four-level rubric.
• Feature request classification template: a choice with a catch-all.
• Confidence thresholds: what to do with the numbers.