Skip to main content

Write effective descriptions

A field's description tells the model what value to produce. Its schema constraints define what values are allowed. Use descriptions to explain the meaning that a type or enum cannot convey on its own.

Struct uses the descriptions you supply without rewriting them.

Describe the decision, evidence and fallback​

“Is this a duplicate?” leaves several interpretations open. A stronger description says what counts, what does not count and what to return when the evidence is missing:

descriptions.schema.json
Download JSON Schema
{
  "type": "object",
  "properties": {
    "duplicate": {
      "type": "boolean",
      "description": "True only when the message explicitly reports more than one charge for the same purchase. A high price or a pending charge alone does not count. Otherwise false."
    }
  },
  "required": [
    "duplicate"
  ],
  "additionalProperties": false
}

This description identifies repeated charges for the same purchase, excludes a high price or pending charge alone, and gives a fallback. Each detail changes how the boolean should be interpreted.

Try the complete request​

Save the schema as descriptions.schema.json. This client loads it unchanged:

Before you run this example

Call https://api.blatent.ai from your server. Set your API key in the same terminal where you run the example:

export BLATENT_API_KEY='YOUR_SERVICE_KEY'

Python requires Python 3.10+ and HTTPX:

python -m pip install "httpx>=0.28,<1"

TypeScript requires Node.js 24+ and uses its built-in fetch. The cURL examples require curl and jq.

Save the displayed files and the selected client in one directory. Run the client there with python example.py, node example.ts or bash example.sh. Downloads use the example's name in place of example.

Download Python
import json
import os
from pathlib import Path
import httpx

request = {
    "input": "The invoice was charged twice.",
    "schema": json.loads(Path("descriptions.schema.json").read_text(encoding="utf-8")),
}
with httpx.Client(
    base_url="https://api.blatent.ai",
    headers={"Authorization": f"Bearer {os.environ['BLATENT_API_KEY']}"},
    timeout=195,
) as client:
    response = client.post("/v1/resolve", json=request)
    response.raise_for_status()
    print(json.dumps(response.json()["output"]))

Illustrative output: {"duplicate":true}.

Apply the same approach to richer outputs​

For an enum, distinguish the labels. For an extracted value, identify its source and units. For generated text, explain the intended content and relevant restrictions. Put shared task context on the enclosing object and field-specific instructions on the field.

If the answer depends on application state, refer to the relevant facts explicitly. If a policy enforces a relationship, describe that relationship too so the model has useful guidance while looking for an acceptable answer.

Guidance is not enforcement​

A description saying “these amounts must add to the total” can improve generation, but it does not make the relationship mandatory. Add a policy for an exact requirement. Clear descriptions and enforced rules complement one another.

A stronger description resolves ambiguity; a longer description is not automatically better. It cannot supply knowledge the model lacks or make contradictory requirements satisfiable. Evaluate changes on representative inputs.

Descriptions are part of a registered schema's content. Changing one requires a new version. Schema registration explains how to roll out that change.