Do you need one?
If you can write the description without looking at a document, or without a specific mistake in mind, skip it. “The date when the invoice was issued” on a field called “Invoice date” adds nothing: the model already reads the field name. Write a description when:- The field name is jargon or ambiguous (“Connote number”, “Box 24a”).
- The model got this field wrong and you can say how.
- You know something about your documents the model cannot infer.
- The field is a dropdown or a repeating group (see below).
The eight jobs a description can do
1. Separate lookalikes. The most valuable move. Name the value the model confuses this field with, and say which one you want.“This is the vehicle identification number (VIN). Do not return the registration number, model, or make.”2. Point at labels and locations. Quote the literal text the value sits next to, including variants, and say where it lives.
“Often labelled ‘B/L No.’, ‘Ref No.’, or ‘Booking No.’, usually at the top right of the first page.”3. Draw the boundary. Say exactly where the value starts and stops.
“Date only. Do not extract the time.”4. Permit an empty answer. Models over-extract when they feel obliged to return something.
“Not every document contains this field, and that is fine. Leave it blank rather than guessing.”5. Supply facts the model cannot know. Conventions specific to your documents or business.
“Purchase order numbers are 9-digit strings starting with ‘2’.”6. Show a good and bad example pair. One concrete pair beats a paragraph of rules.
“Correct: ABC123. Incorrect: ‘Registration no: ABC123’ (the label must be stripped).”7. Constrain repetition. For fields that return multiple values, state the expected count and forbid duplicates.
“Return each person as a separate entry. Do not merge names or repeat a name that appears in several places.”8. Give fallback logic. Tell the model where to look first, where to look next, and what never to use.
“Prefer the date next to ‘Effective from’ or ‘Effective date’. Otherwise use the date next to wording like ‘This agreement was made on’. Do not use a date from the signature block.”
Style
- One or two sentences, one failure mode. Long descriptions are the exception, and every word is processed on every extraction.
- Positive before negative. “Extract X, not Y” beats a bare “Do not extract Y”, which leaves the model without a target.
- Prune when you add. Descriptions accumulate edge cases and eventually contradict themselves. Reread the old sentences when adding a new one.
- Any language works. Descriptions in the document’s own language perform fine.
Dropdown (options) fields
If the labels are short or domain-specific, say what each value means:“Whether the deal includes an option: ‘Call’ (buy) or ‘Put’ (sell).”If the value is inferred rather than read off the page, give the trigger for each option, including the unclear case:
“Return ‘true’ if the receipt includes a meal. If there are only drinks, return ‘false’. If the receipt does not say what was ordered, return ‘false’.”
Grouped and repeating fields
Describe the parent, not just the children: what one instance of the group represents, and what makes two instances distinct. For groups that can repeat, add the cardinality constraint from job 7 up front (“expect at most three per document”, “no duplicates”). Returning too many instances is the known failure mode.What descriptions cannot do
They guide the prediction. They do not reliably reformat output (use formatting options), they do not enforce constraints (use validation rules), and they do not override your reference examples; the model reads all of these together.Checklist
- Says something the field name does not.
- Targets a specific mistake or a specific fact about the documents.
- Tells the model what to extract, not only what to avoid.
- Says whether an empty answer is acceptable.
- As short as it can be while still doing its job.