Writing good statements and labels

Every capability scores your words against the input. A statement, a label name, a scale level, a question and a field description all act as the instruction. The model reads that text literally.

So one rule covers every capability: the text must describe the case, not the verdict. "yes" and "no" describe nothing. "A", "B" and "1" to "5" describe nothing either.

Statements for yes-no

A statement is a sentence that is true or false about the text. Write it in the third person, as a claim about what the text says. Put one idea in it.

Split compound judgments into separate statements and send them in one statements batch. Read Batching for the shape of the response.

when_true and when_false hints

Without hints, the API scores your statement alone and returns that raw score. With hints, it scores when_true against when_false and normalizes the pair. The hint text replaces your statement as the thing being scored, so a verdict word destroys the signal.

This measured pair uses the same text and the same statement. Only the hints change.

{"statement":"The customer expresses urgency.","answer":true,"probability":1}

The second call is wrong. "yes" and "no" carry no meaning about urgency, so the pair scores noise.

Write each hint as a short description of the world in that case:

{
  "statement": "The letter states five or more years of backend experience.",
  "when_true": "the letter states a number of years of backend engineering experience that is five or more",
  "when_false": "the letter states no years of experience, or fewer than five"
}

Send both hints together. If you send when_true alone, the API scores it against the generic phrase none of the above. If you send when_false alone, your statement takes the true side.

Labels for classify

Label names must be words that describe the content. Descriptions raise the winner’s probability further. This ticket went through classify three ways:

I was charged twice for my subscription this month and support has not replied.

The letters name nothing, so the model splits the weight and picks a meaningless winner.

The described form is the object form of labels:

{
  "labels": {
    "billing": "a question or dispute about an invoice, charge, refund or price",
    "bug": "the product behaves incorrectly or fails",
    "sales": "a request for a quote, a demo or a new contract"
  }
}

Your code still reads back the short name in label and in scores. The description only steers the model. Make labels mutually exclusive, and add a catch-all label such as other when the real world has cases outside your set.

Levels for rate

A scale is a list of level descriptions, ordered low to high. Numbers are not descriptions. This message went through rate twice, with four levels each time:

This is the third time I have written. My order still has not shipped and nobody answers. If it is not fixed today I am cancelling my account.

{"score":1.423,"level":2,"confidence":0.247,"scores":[0.157,0.279,0.548,0.016]}

The numeric scale spreads weight over all four levels and reports confidence 0.247. The described scale (["calm and factual","mildly annoyed","clearly frustrated","angry and threatening to cancel"]) rules out both calm levels and reports 0.5. It still splits the top two levels evenly, and the confidence reports that split honestly.

Keep the levels on one axis, and make the step between neighbours the same size. The API accepts two to ten levels. Four or five is usually enough.

Questions for answer and entities

answer turns each question into an extraction label. A bare noun matches the first thing of that kind, and that is rarely the thing you want. Three questions against one invoice line:

Invoice 8812 from Meridian Design. Issued 3 March 2026 by Nadia Rossi. Payment is due 2 April 2026.

{
  "results": [
    {"question":"date","answer":"3 March 2026","probability":0.998,"start":42,"end":54},
    {"question":"When is the invoice due?","answer":"2 April 2026","probability":0.988,"start":86,"end":98},
    {"question":"Who issued the invoice?","answer":"Meridian Design","probability":0.979,"start":18,"end":33}
  ]
}

The text holds two dates. "date" returned the issue date. The full question returned the due date. Name the role, not the type: “the date the payment is due”, not “date”.

The same rule applies to entities types and to verify fields. For extract, a property description becomes the field instruction. Without one, the API falls back to title, then to the property name with underscores turned into spaces. So invoice_number works, and n1 does not.

Worked example: the cover-letter false positive

A vague statement scores tone instead of fact. This letter states no software experience at all.

Dear hiring manager, I am so excited about this backend engineer role. I spent the last three years managing a coffee shop […] I have no professional software experience yet, but I am a passionate self-starter and I know I would be a great addition to your team.

Two statements against that one text, in one statements batch:

{
  "results": [
    {"statement":"The candidate is a good fit.","answer":true,"probability":1},
    {"statement":"The letter states the candidate has professional software engineering experience.","answer":false,"probability":0}
  ]
}

The vague statement returns true at probability 1. Nothing in the letter supports it. The model matched enthusiasm, because “a good fit” describes an opinion and the letter is full of opinion.

The precise statement returns false at probability 0. It names something the text either says or does not say. No threshold can rescue the first statement. Only the wording can.

Checklist

• Describe the case. Never write yes, no, true, false, A, B or a bare number.
• One idea per statement, per label and per level. Batch the rest.
• Claim what the text says, not what you conclude about the subject.
• Name the role in a question, not the data type.
• Add descriptions to labels, entity types and schema fields.
• Keep label names short and stable; your code reads those, not the descriptions.

Next