Last date modified: 2026-Oct-14

Best practices for writing Custom insight prompts

Use this guide as you create Custom insights. Small changes in how you write your insight prompts can dramatically improve quality and consistency. See Custom analyses to add Custom insights to a project.

How to use this guide:

General tips

General tips apply to all analysis types: extraction, classification, and narrative alike. Start here before diving into type-specific guidance.

Ask for one thing at a time

Focus on one detail at a time, such as one question, one field, or one answer format. Bundling multiple tasks into a single open-ended question leads to inconsistent structure. Separate each field or use a clearly defined schema.

Describe how to handle edge cases

Documents are messy. Tell the system what to do when data is missing, partial, or ambiguous.

Give brief positive and negative examples

When asking the system to make a judgment call, like classifying a field, a couple of short examples go a long way toward defining the expected behavior.

Specify the output format

Tell the system exactly how you want the answer formatted, such as a Yes/No answer, a date, or a category count. Without this, responses will vary in style and be harder to use consistently.

For Custom analyses projects, do not specify a date format in your prompt when Date is selected as the output Field Type. Dates display for the project based on your browser's regional settings. Use Fixed Length Text as the Field Type if you want to specify a desired date format, if you want to display date and time, or if you need to handle multiple dates in your prompt. See Adding Custom insights and prompt criteria for more information.

Assign a role for context

Assigning a domain role when the question needs subject matter judgment. This can improve how the system interprets domain-specific language and what level of precision it applies.

Extraction tips

Extraction tips help when your analysis pulls specific values out of documents: dates, amounts, names, identifiers. The challenge with extraction is getting consistent, structured output across diverse document formats.

Normalize extracted values

Documents express the same value in different formats: "$1,234.56" vs "1.234,56 EUR" vs "one thousand two hundred thirty-four dollars." Tell the system exactly how to normalize.

Handle multi-value fields

A document may contain multiple phone numbers, addresses, or dates. Tell the system which one to return, or how to return all of them in a consistent structure.

Anchor to document structure

When you know your documents share a consistent layout (such as, you are processing a batch of purchase orders or a standard form), it can be worth trying to tell the system where in the document to look. This is most useful when analyzing many similar documents whose structure is predictable. Positional anchoring can sometimes reduce ambiguity when the same value appears in headers, footers, and body text.

Classification tips

Classification tips help when your analysis assigns a label or category to documents. The challenge is getting consistent labels from a controlled vocabulary that can be used for filtering, routing, and reporting at scale.

Define all valid categories up front

Provide the complete list of valid labels. Open-ended classification ("what type is this?") produces inconsistent taxonomies like "business agreement" vs "service arrangement" vs "vendor document" for the same document.

Include a catch-all category

Without "Other" or "None of the above," the system force-fits every document into the closest label, even when none apply. A catch-all can help reduce misclassifications.

Define decision boundaries for ambiguous cases

Do not just list labels. Describe what distinguishes borderline cases. An email about a project is Correspondence, not a Report. A memo containing financial figures is not necessarily a Financial Record.

Narrative/Insight tips

Narrative / Insight tips help when your analysis generates summaries, descriptions, or open-ended assessments. The challenge is getting consistent length, appropriate depth, and grounded claims across a large document population.

Constrain output length and focus

Without bounds, summaries range from one sentence to five paragraphs unpredictably. Set explicit length and tell the system what to prioritize.

Require evidence and citations

Tell the system to reference specific passages or facts from the document. This prevents hallucination, aids reviewer verification, and surfaces which parts of the document support the conclusion.

Separate observations from inferences

In investigation and compliance contexts, it's critical to distinguish what the document explicitly states from what can be inferred or concluded. Ask the system to separate the two.

Feedback