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:
- Workflow: Start with the General tips, then explore Extraction tips, Classification tips, and Narrative/Insight tips.
- Example User Goal: The outcome you might try to achieve with a custom analysis field.
- Don't / Do example table: Shows how vague versus explicit field descriptions affect the system's results.
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.
Click to view Do and Don't examples.
| Don't | Do |
|---|---|
| EXAMPLE PROMPT: Does this document have any handwriting, annotations, stamps, sticky notes, margin notes, correction marks, or other manual markings? Describe what you find.
EXAMPLE RESPONSE: The document contains a small handwritten note in the left margin that reads "See clause 4.2 — RU." It also has what appears to be a stamped "RECEIVED" date in the upper right corner. I did not find any sticky notes, correction tape, or other manual markings.
By asking about six different things at once and requesting description, you get a multi-paragraph response that's hard to parse. The system conflates handwriting with stamps and annotations because the prompt bundles them together.
|
EXAMPLE PROMPT: Does this document contain any handwritten text? Answer only Yes or No.
EXAMPLE RESPONSE: Yes
One question, one answer format. The response is a clean Yes or No you can act on. If you also need stamp detection, create a separate analysis for it.
|
Describe how to handle edge cases
Documents are messy. Tell the system what to do when data is missing, partial, or ambiguous.
Click to view Do and Don't examples.
| Don't | Do |
|---|---|
|
EXAMPLE PROMPT: Extract the date from this document.
EXAMPLE RESPONSE (NO DATE PRESENT): I'm sorry, I couldn't find a specific date in the document. However, based on the context, it may have been written around mid-2024. Without edge-case rules, the system guesses when data is missing. It might hallucinate a date from context or return inconsistent formats across documents. You can't rely on the output being consistent.
|
EXAMPLE PROMPT: Extract the primary document date, formatted as YYYY-MM-DD. Follow these rules:
- If multiple dates appear, return the one that represents the document's execution, issue, or effective date. - If no date is found, respond with exactly: N/A - If the date is partial (e.g. only a month and year), return what is available using XX for unknown parts, e.g. 2024-10-XX. EXAMPLE RESPONSE (NO DATE PRESENT): N/A Every edge case has a defined behavior. The system knows to return N/A (not apologize), pick the execution date (not a body reference), and use XX for unknowns. You get predictable output regardless of document quality.
|
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.
Click to view Do and Don't examples.
| Don't | Do |
|---|---|
|
EXAMPLE PROMPT: Does this document contain a signature? Answer Yes or No.
EXAMPLE RESPONSE: Yes
Without boundary examples, "signature" is ambiguous. The system treats email sign-offs and typed names as signatures, producing false positives that defeat the purpose of the detection. |
EXAMPLE PROMPT: Does this document contain a formal signature? Answer only "Yes" or "No".
A formal signature is a handwritten signature, a /s/ (conformed signature) line, a digital signature block, or a witnessed mark. Examples: - /s/ John Smith → Yes - Handwritten cursive name above a signature line → Yes These are NOT signatures: - "Best regards, John Smith" at the end of an email → No - A typed name at the bottom of a report (e.g. "Prepared by: Jane Doe") → No EXAMPLE RESPONSE: No Positive and negative examples define the boundary precisely. The system now knows that "Best regards" and "Prepared by:" are not formal signatures, while /s/ lines and handwritten marks are.
|
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.
Click to view Do and Don't examples.
| Don't | Do |
|---|---|
|
EXAMPLE PROMPT: What are the financial details of this document?
EXAMPLE RESPONSE: This invoice was issued by Bright Horizon Consulting LLC on January 15, 2025. The total amount due is $17,320.00 for consulting services including strategic planning and executive coaching.
This prompt doesn't name the fields you need or specify a format. The system returns a narrative. It mentions the vendor and total, but not in a consistent structure. Run to run, the format will vary. |
EXAMPLE PROMPT: Extract the following from this financial document and respond in this format:
Vendor: [company that issued the document] Document Number: [invoice number, PO number, or other identifier] Total: [total amount as a number, no currency symbol] Currency: [three-letter code like USD] If a field is not present, write "N/A". EXAMPLE RESPONSE: No Vendor: Bright Horizon Consulting LLC
Document Number: BHC-2025-0187 Total: 17320 Currency: USD Every field is named, the format is defined, and missing-value handling is explicit. The system knows exactly what you need and returns it in a consistent structure every time. |
Format spectrum: You can make your format as structured as you need. The example above uses labeled fields, simple and readable. For more technical workflows you can go further:
Labeled fields → Vendor: Acme Corp
Delimited → Acme Corp; BHC-2025-0187; 2025-01-15; 17320; USD
JSON → {"vendor": "Acme Corp", "total": 17320, ...}
Pick whatever fits your workflow. The key principle is the same—tell the system exactly what format you want.
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.
Click to view Do and Don't examples.
| Don't | Do |
|---|---|
|
EXAMPLE PROMPT: Is there anything problematic in this document?
EXAMPLE RESPONSE (EMAIL WITH VEILED BIAS): There's nothing overtly problematic, though the tone could be interpreted as slightly cynical. The email discusses hiring preferences but doesn't contain anything explicitly inappropriate.
Without a role or taxonomy, the system applies a general-audience lens. Subtle policy concerns like favoritism or hiring bias get dismissed as "slightly cynical." An HR compliance analyst would flag this immediately. |
EXAMPLE PROMPT: You are an HR compliance analyst reviewing internal communications for workplace conduct issues. Classify this document into exactly one of these categories:
- Hostile: aggressive, demeaning, or threatening language directed at an individual - Policy Concern: potential violation of company policies (hiring, discrimination, retaliation) without overtly hostile language - Clean: no workplace conduct issues detected Respond with only the category name. EXAMPLE RESPONSE (EMAIL WITH VEILED BIAS):: Policy Concern
The role ("HR compliance analyst") activates domain expertise. The taxonomy gives the system three precise labels instead of a vague yes/no. Veiled references to favoritism now correctly map to "Policy Concern." |
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.
Click to view Do and Don't examples.
| Don't | Do |
|---|---|
|
EXAMPLE PROMPT: What is the total amount on this document?
EXAMPLE RESPONSE (US INVOICE): The total amount is $35,984.90.
EXAMPLE RESPONSE (EU INVOICE): The total is €51.480,00.
The system mirrors the document's formatting: dollars with commas, euros with periods for thousands. You'd need to account for every locale variation, and currency is sometimes missing entirely. |
EXAMPLE PROMPT: Extract the final total amount from this document. Follow these formatting rules exactly:
- Return only a plain number with exactly two decimal places (e.g. 1234.56) - Do not include currency symbols ($, €, £), commas, or text - Use a period as the decimal separator regardless of the document's locale - On a new line, return the three-letter currency code (e.g. USD, EUR, GBP) EXAMPLE RESPONSE (US INVOICE): 35984.90
USD EXAMPLE RESPONSE (EU INVOICE): 51480.00
EUR Explicit formatting rules produce identical output structure regardless of the source document's locale. Every value uses period decimals, no symbols, and always includes the currency code on a separate line. |
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.
Click to view Do and Don't examples.
| Don't | Do |
|---|---|
|
EXAMPLE PROMPT: Extract the phone number from this document.
EXAMPLE RESPONSE (3 NUMBERS IN DOC): The document contains several phone numbers:
(212) 555-0147 belongs to the sender, (312) 555-0298 appears to be the office line, and 1-800-555-0199 is the customer service number. |
EXAMPLE PROMPT: Extract all phone numbers from this document. Return each number on a separate line in the format +1-XXX-XXX-XXXX. If no phone numbers are found, respond with: N/A
EXAMPLE RESPONSE (3 NUMBERS IN DOC): +1-212-555-0147
+1-312-555-0298 +1-800-555-0199 |
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.
Click to view Do and Don't examples.
| Don't | Do |
|---|---|
|
EXAMPLE PROMPT: Who approved this purchase order?
EXAMPLE RESPONSE: The purchase order appears to have been approved by several people. John Miller is mentioned in the header as the requesting manager, and there are also references to Sarah Kim in the vendor notes section.
|
EXAMPLE PROMPT: Extract the names of the people who approved this purchase order. Look specifically in the approval block at the bottom of the document (after "Authorized By" or similar closing section). Return each approver's name and title on a separate line.
EXAMPLE RESPONSE (3 NUMBERS IN DOC): John Miller, Procurement Manager, Acme Corp Sarah Kim, VP of Finance, Acme Corp
|
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.
Click to view Do and Don't examples.
| Don't | Do |
|---|---|
|
EXAMPLE PROMPT: What type of document is this?
EXAMPLE RESPONSE (SAME DOC TYPE): Run 1: "This is a vendor agreement"
Run 2: "Service arrangement" Run 3: "This appears to be a binding agreement between two companies" Without a taxonomy, the system invents labels on each run. You can't filter or route on these because the same document gets different labels every time. You need exact, repeatable categories. |
EXAMPLE PROMPT: Classify this document into exactly one of these categories. Respond with only the category name.
- Agreement: any binding arrangement, including service agreements, leases, licenses - Correspondence: emails, letters, memos, or other person-to-person communications - Legal Filing: court documents, motions, briefs, complaints, subpoenas - Financial Record: invoices, receipts, bank statements, tax filings - Report: incident reports, audit reports, inspection reports - Other: anything that does not fit the above categories EXAMPLE RESPONSE: Agreement
A closed taxonomy with definitions eliminates label drift. The system picks from exactly 6 options, and each option has boundary examples so ambiguous documents (like an email about a project) get classified consistently. |
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.
Click to view Do and Don't examples.
| Don't | Do |
|---|---|
|
EXAMPLE PROMPT: Classify this document: Invoice, Agreement, or Legal Filing.
EXAMPLE RESPONSE (HR MANUAL POLICY): Agreement
|
EXAMPLE PROMPT: Classify this document into one of these categories: Invoice, Agreement, Legal Filing, or Other. If the document does not clearly fit Invoice, Agreement, or Legal Filing, use "Other."
EXAMPLE RESPONSE (HR MANUAL POLICY): Other
|
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.
Click to view Do and Don't examples.
| Don't | Do |
|---|---|
|
EXAMPLE PROMPT: Is this a financial document? Answer Yes or No.
EXAMPLE RESPONSE (EMAIL WITH BUDGET NUMBERS): Yes
|
EXAMPLE PROMPT: Is this document a Financial Record? Answer only "Yes" or "No".
A Financial Record is a document whose primary purpose is recording a financial transaction or reporting financial position. Examples: - Invoice, receipt, bank statement, tax return →Yes - Email discussing a budget or mentioning dollar amounts → No - Inspection report with cost estimates → No (the primary purpose is the inspection findings, not the financial transaction) EXAMPLE RESPONSE (EMAIL WITH BUDGET NUMBERS): No
|
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.
Click to view Do and Don't examples.
| Don't | Do |
|---|---|
| EXAMPLE PROMPT: Summarize this document.
EXAMPLE RESPONSE:This compliance audit report was prepared by Stonebridge Compliance Partners for Pacific Northwest Credit Union covering the period from January 1 to December 31, 2024. The audit reviewed 450 consumer loan files and 120 mortgage applications across six branches, focusing on compliance with ECOA, TILA, and the Fair Housing Act. Four key findings were identified. Finding #1 (High Risk) involved ECOA adverse action notice failures in 4% of files, disproportionately affecting younger applicants... [continues for 3 more paragraphs] Without length or focus constraints, the system dumps everything: methodology, background, and every finding. A reviewer scanning 500 documents needs the essential takeaway in seconds, not a five-paragraph essay. |
EXAMPLE PROMPT: Summarize this document in exactly 2-3 sentences. Focus on: EXAMPLE RESPONSE:1. What the document is and who created it 2. The most important finding, decision, or event 3. Any required next steps or actions Do not include background or methodology. Be specific: include names, dates, and numbers. Stonebridge Compliance Partners' 2024 audit of Pacific Northwest Credit Union found two high-risk issues: ECOA adverse action notice failures in 4% of loan files and mortgage pricing disparities of 38 basis points in majority-minority census tracts. The overall risk rating is Elevated, and the auditor recommends engaging an independent fair lending consultant and implementing automated notice tracking. The sentence count, focus areas (who/what/next steps), and specificity requirement ("include names, dates, and numbers") produce a dense, actionable summary every time. |
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.
Click to view Do and Don't examples.
| Don't | Do |
|---|---|
| EXAMPLE PROMPT: Does this document contain evidence of bid rigging? EXAMPLE RESPONSE:Yes, the document contains some indicators that could suggest coordinated bidding behavior between the parties. |
EXAMPLE PROMPT: Does this document contain evidence of bid rigging or market allocation? Answer "Yes" or "No", then on a new line quote the most relevant passage (verbatim, in quotation marks) from the document that supports your answer. If no relevant passage exists, write "No supporting passage found." EXAMPLE RESPONSE:"I will focus our bids on the Illinois and Wisconsin RFPs, and you take the lead on Indiana and Ohio. That way we're not undercutting each other on price." |
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.
Click to view Do and Don't examples.
| Don't | Do |
|---|---|
| EXAMPLE PROMPT: What are the key takeaways from this incident investigation report? EXAMPLE RESPONSE:The maintenance team was clearly trying to cover up the equipment failure and delayed reporting it to management, likely because they knew the preventive maintenance schedule had been skipped. |
EXAMPLE PROMPT: Analyze this incident investigation report. Provide two clearly labeled sections: EXAMPLE RESPONSE:STATED FACTS: What the report explicitly documents (with direct quotes where possible). POTENTIAL INFERENCES: What a reviewer might reasonably conclude from the findings, clearly marked as inference rather than fact. STATED FACTS: The report documents that elevated vibration readings were first recorded on August 12, 2023 but were not escalated to plant management until October 3. The shift supervisor described the initial readings as "within acceptable tolerance." A maintenance log entry from Sept 18 noted "Martinez aware of continued vibration anomaly." POTENTIAL INFERENCES: The seven-week gap between initial detection and management escalation, combined with the Sept 18 log entry, could suggest the shift team had more awareness of the severity than the timeline of formal reports implies. |