Tips for creating effective attributes

Well-designed attributes return cleaner data, require less refinement, and scale more effectively across document sets.

Creating effective attributes is an iterative process. You define what to extract, then refine that definition based on how the system interprets your language across real documents. The following guidance focuses on writing clear definitions, diagnosing results, and improving accuracy over time.

Start with a simple definition

Begin with a straightforward description of what you want to extract. Avoid adding constraints, conditions, or examples until you see how the initial definition performs.

Starting simple makes it easier to understand how your language is interpreted before introducing nuance.

Example
“Extract the retainer fee from the document.”

Write clear, plain-language descriptions

Describe the concept as if you were explaining it to someone unfamiliar with the document. Clear, plain language helps the system identify the correct information more consistently.

Avoid:

• Formatting cues.
• Section numbers.
• Layout-dependent instructions.

Focus on meaning, not placement.

Example
“A rate card lists the roles or positions and the hourly rate for each.”

Refine an attribute

Refining an attribute combines a repeatable set of steps with diagnostic judgment based on the results you see. Refinement is expected and typically occurs over multiple evaluation cycles.

Step-by-step: refine an attribute

1. Select the attribute you want to refine.
2. Edit the attribute definition to clarify intent or reduce ambiguity.
3. Re-run extraction to apply the updated definition.
4. Evaluate results across a small set of documents.

Repeat as needed.

Diagnose unexpected results

Use the following patterns to adjust the definition based on how results differ from expectations.

Results are too broad
The attribute matches unrelated content.

• Tighten the definition with more specific language.
• Specify the expected answer format (for example, “Return the answer as a percentage only.”).
• Set an appropriate value type, such as Number for numeric results.

Results are too narrow or missing
Expected values are not returned.

• Start broader and remove unnecessary constraints.
• Add positive and negative examples to clarify intent.
• Confirm the target information is present in the documents being evaluated.

Results vary across documents
The definition works for some documents but not others.

• Validate the definition against documents you know contain the target information.
• Expand testing to mixed document types only after results are consistent.
• Cross-check a document manually or with AI Assistant to confirm the value exists.

Use examples deliberately

When adding examples:

• Use positive examples to show what should be extracted.
• Use negative examples to show what should be excluded.
• Limit examples to 3–5 to avoid overfitting.

Examples should clarify intent, not replace a clear definition.

Advanced: attributes that require multi-step logic

Some attributes depend on context or multi-step reasoning. In these cases, it can help to describe the logic used to determine the value explicitly.

Example

Extract the retainer fee by following these steps:

1. Locate the fees section of the document.
2. Identify retainer fees expressed as percentages at the start of the term.
3. Treat X% as standard; all other percentages indicate negotiated rates.
4. Return the percentage and whether it is standard or negotiated.

Answer format
“Retainer fee %; standard or negotiated.”

Use this approach sparingly, only when simpler definitions are insufficient.

Use evaluation feedback to improve accuracy

Evaluation feedback closes the refinement loop.

During evaluation, review extracted values and mark them as correct or incorrect. When marking a value as incorrect, provide the correct answer when possible.

Evaluation feedback helps identify false positives and missed matches, improves future extraction accuracy, and builds confidence in refined definitions. If results are unclear, cross-check a document using AI Assistant and compare its response with the extracted value to identify gaps or inconsistencies.

Validate results before scaling

Before applying an attribute to a large collection, validate it across a representative sample of documents.

Validation helps you:

• Catch edge cases early.
• Avoid scaling inaccurate definitions.
• Build confidence that the attribute will perform consistently.

Also, confirm document quality when the results look wrong. Common issues include:

• Scanned documents with poor text quality.
• Password-protected or locked files.
• Corrupted source files.
• The target information isn't actually present in the document.

Always confirm the data exists before refining the definition further.

Related topics

• Attributes overview
• Create a custom attribute
• Evaluate an attribute
• Refine an attribute