Writing Descriptions for Smart Data Capture

What are Descriptions?

Smart Data Capture descriptions are instructions you write for the AI. Think of them as:

• What to extract: The specific information you need
• Where to look: Which sections or pages contain it
• How to format: The structure of the output
• Edge cases: What to do when data is missing or ambiguous

Time investment: Spend 5-10 minutes crafting a good description to save hours of manual review across hundreds of contracts.

0: Basics: How to Add or Edit Metadata Descriptions

1. Go to the "Contract Metadata" Section: Hover over "Manage" in the left sidebar and click "Contract Metadata."

2. Select the Contract Type: Choose the relevant contract type (e.g., Employment Agreement, Master Service Agreement).

3. Choose the Metadata Field: Select the specific metadata field you want to edit (e.g., Term Length, Termination Date, Governing Law). Hover over the metadata field and click the three dots on the right. Click on "Edit Field."

4. Write Your Description: Use the guidelines below to craft a clear and accurate description.

5. Save: Click "Save" to update the description.

1: Core Principles for Writing Effective Descriptions

The SPACE Framework

The Three-Part Description Structure

Every strong description should have:

1. WHAT: The information to extract "Extract the liability cap amount..."
2. WHERE: Location guidance (optional but recommended) "...typically found in the Limitation of Liability section..."
3. HOW: Format and edge case handling "...output as a number only. If uncapped, output '0'"

Example

❌ Weak: "Liability Cap: The liability cap"

✅ Strong: "The maximum amount the Supplier is liable to pay the Customer for damages. Typically found in the Limitation of Liability section. Output as a number only (e.g., 100000 for $100,000). If the liability is uncapped or unlimited, output 0. If there are different caps for different breach types, output the general liability cap."

2: Writing Guidelines for Legal Metadata

1. Be Specific About Parties

Legal contracts involve multiple parties with different roles. Always clarify which party you're referring to.

✅ Do: "The maximum liability of the Supplier (also referred to as 'Vendor' or 'Service Provider') to the Customer for any claims arising from this agreement"

🚫 Don't: "The maximum liability of the parties"

Why: The AI might conflate mutual liability caps or extract the wrong party's obligations.

Party Identification Checklist:

• Is this about Customer, Supplier, or mutual obligations?
• Do contracts use alternate terms (Vendor, Client, Provider)?
• Are there guarantors or third-party beneficiaries?

2. Disambiguate Similar Concepts

Legal contracts often have related but distinct concepts. Clarify differences explicitly.

✅ Do: "The initial term length starting from the Effective Date, NOT including any renewal terms. This is the first committed period before any renewals take effect."

🚫 Don't: "The term length of the contract"

Common Ambiguities to Address:

• Initial Term vs. Renewal Term vs. Total Potential Term
• Notice Period vs. Notice Deadline vs. Notice Requirements
• Termination Date vs. Expiration Date vs. Renewal Date
• Payment Terms (net days) vs. Payment Amount vs. Payment Schedule
• General Liability Cap vs. IP Infringement Liability vs. Data Breach Liability

3. Handle Conditional Logic

Many contract provisions are conditional. Specify how to handle "if-then" scenarios.

✅ Do: "Whether the contract automatically renews. Output 'Yes' if the contract states it will renew automatically unless either party provides notice. Output 'No' if renewal requires affirmative action or mutual written agreement. Output 'N/A' if the contract is perpetual with no renewal provisions."

🚫 Don't: "Whether the contract renews automatically"

Conditional Scenarios to Consider:

• If X condition exists, extract Y; otherwise extract Z
• Different values based on contract value or term length
• Graduated terms (e.g., payment schedules that change over time)
• Caps that differ by breach type or time period

4. Specify Output Format Precisely

Especially for short answer fields, format inconsistency causes downstream problems.

✅ Do: "The names and email addresses of all Customer signatories. Output each person on a new line in the format: 'Full Name (Title) - email@domain.com'. Example: John Smith (VP Legal) - john.smith@company.com Jane Doe (CFO) - jane.doe@company.com"

🚫 Don't: "The names and contact info of Customer signatories"

Format Specifications:

• Date formats: "MM/DD/YYYY" or "YYYY-MM-DD" or "DD Month YYYY"
• Number formats: "100000" vs "$100,000" vs "100,000.00"
• List separators: newlines vs. semicolons vs. commas
• Name formats: "Last, First" vs. "First Last"
• Address formats: single line vs. multi-line

5. Identify Alternative Clause Names

Different contracts use different terminology for the same concept.

✅ Do: "The governing law jurisdiction. This may be labeled as 'Governing Law', 'Choice of Law', 'Applicable Law', or found within a 'General Provisions' or 'Miscellaneous' section. Extract only the jurisdiction (e.g., 'New York' or 'California'), not the full clause text."

🚫 Don't: "The governing law of the contract"

Common Variations:

• Liability Cap / Limitation of Liability / Maximum Liability
• Indemnification / Hold Harmless / Defense Obligations
• Confidentiality / Non-Disclosure / Proprietary Information
• Intellectual Property / IP Rights / Ownership of Work Product
• Term / Duration / Contract Period / Agreement Length

6. Provide Section Location Hints

Help the AI focus on relevant contract sections.

✅ Do: "The termination notice period required from either party. This is typically found in the 'Term and Termination' or 'Termination' section, often stated as '[X] days written notice'. Output only the number of days (e.g., 30, 60, 90)."

🚫 Don't: "The termination notice period"

Location Strategies:

• Common section names where data appears
• Proximity to other related clauses
• Typical page ranges (e.g., "usually in first 3 pages")
• Whether in main agreement vs. exhibits/schedules

7. Handle Missing or Ambiguous Data

Tell the AI what to do when information isn't clear.

✅ Do: "The number of days after invoice date that payment is due (Net Terms). Typically expressed as 'Net 30', 'Net 60', etc. Output only the number. If the contract says 'upon receipt' or 'immediate payment', output 0. If payment terms are not specified, output 'Not specified'. If terms vary by payment type or amount, extract the default/standard term."

🚫 Don't: "The payment terms in days"

Edge Cases to Address:

• What if the clause is entirely missing?
• What if there are conflicting values?
• What if the language is ambiguous?
• What if there are multiple scenarios?

9. Use Examples from Your Contracts

If your contracts use specific phrasing or unusual structures, include that in the description.

✅ Do: "The annual software license fee. In our contracts, this is typically listed in 'Exhibit A - Pricing Schedule' as 'Annual SaaS Subscription Fee' or 'Platform License - Annual'. Do NOT include one-time implementation fees or per-user charges unless they're part of the base annual fee."

🚫 Don't: "The annual license fee"

When to Use Contract-Specific Examples:

• Your organization uses non-standard terminology
• You have specific fee structures or pricing models
• Your contracts have unique sections or exhibits
• There's industry-specific language

10. Leverage Multi-Dropdown Fields Effectively

For multi-dropdown fields, you don't need to list all options in the description - the AI already receives them.

✅ Do: "Select all types of breaches that are excluded from the general liability cap for the Supplier. Look for language like 'except for', 'excluding', 'does not apply to', or 'notwithstanding the limitation above'."

🚫 Don't: "Select from: Breach of Confidentiality, IP Infringement, Gross Negligence, Fraud, Death or Bodily Injury, Breach of Data Security"

Why: The AI automatically sees dropdown options. Your description should focus on HOW to identify which options apply.

3. Choosing the Right Field Type

The field type you select dramatically impacts extraction accuracy. Here's when to use each type:

Decision Tree

Is the answer one of a predefined set of options? → YES: Use Dropdown or Multi-Dropdown → NO: Continue...

Is the answer a number with units? → Currency amount: Use Currency field → Time period: Use Duration field
→ Calendar date: Use Date field → Other number: Use Number field → NO: Continue...

Is the answer Yes/No or True/False? → YES: Use Checkbox → NO: Continue...

Is the answer a few words or a sentence? → YES: Use Short Answer → NO: Use Paragraph

Field Type Best Practices

When to Split Fields

Sometimes what seems like one field should be multiple:

❌ Single Field: "Contract Parties" ✅ Multiple Fields:

• "Customer Legal Name"
• "Customer Signing Authority"
• "Supplier Legal Name"
• "Supplier Signing Authority"

❌ Single Field: "Liability Caps" ✅ Multiple Fields:

• "General Liability Cap"
• "IP Infringement Liability Cap"
• "Data Breach Liability Cap"
• "Liability Cap Exclusions" (Multi-dropdown)

Why: Separate fields enable better filtering, reporting, and accuracy

4. Iterative Improvement & Testing

Good descriptions are rarely perfect on the first try. Here's a systematic approach to refinement:

The 20-minute Improvement Cycle

1. Write Initial Description (5 min)
   • Start with SPACE framework
   • Include What, Where, How
2. Test on Sample Contracts (5 min)
   • Run on 5-10 representative contracts using the AI Sandbox
   • Check AI Explanation for reasoning
   • Note patterns in errors
3. Identify Failure Patterns (2 min)
   • Wrong value extracted
   • Value not found when it exists
   • Wrong format
   • Ambiguity in similar clauses
4. Refine Description (3 min)
   • Add disambiguation
   • Clarify edge cases
   • Improve location hints
5. Re-test & Validate (5 min)
   • Test on same samples
   • Check if improvements worked
   • Test on new edge cases
6. Deploy & Monitor (ongoing)
   • Check extraction quality periodically
   • Gather feedback from team
   • Adjust as contract templates change

Using AI Explanations for Debugging

The AI Explanation tooltip is your best debugging tool.

To help you understand how SpotDraft AI makes its decisions, there's an additional output with every metadata extraction that explains the AI's reasoning. This adds a layer of transparency and makes the AI generated results more explainable, so that you can trust them better.

You can find this explanation in the tooltip by hovering over the "Suggested by AI" text next to the extracted value.

SpotDraft AI also outputs a reason for the values it couldn't extract in the contract. This may be because the value isn't present in the contract, or is ambiguous, or the AI simply misunderstood. You can leverage the reasons for such values to understand how the AI is interpreting your description and make necessary changes.

Here's how to interpret it:

Scenario 1: Value Not Found

AI Says: "The contract does not explicitly mention payment terms"

What This Means:

• The AI searched but couldn't locate the information
• Either: Value truly isn't there, OR
• Your description isn't pointing to where it actually appears

Fix It:

• Review contract manually - is the value there?
• If yes: Add section location hints
• If language is different: Add alternative phrasings
• If in non-standard location: Update "where" guidance

Scenario 2: Wrong Value Extracted

AI Says: "Based on Section 5.2, the renewal term is 1 year" Correct Answer: Initial term is 1 year (not renewal)

What This Means:

• AI found a duration but confused initial vs. renewal
• Description lacks disambiguation

Fix It: Add: "The initial term starting from the Effective Date, NOT including any renewal periods. If the contract states '1 year initial term with 1 year renewals', output only the initial 1 year."

Scenario 3: Incorrect Format

AI Says: "The liability cap is one hundred thousand dollars" Expected: 100000

What This Means:

• AI found the right value but wrong format

Fix It: Add: "Output as a number only without currency symbols or commas (e.g., 100000 for $100,000)"

Scenario 4: Ambiguous Answer

AI Says: "The liability cap could be $50,000 under Section 8.1 or $100,000 under Section 8.3"

What This Means:

• Multiple potential values exist
• Need to clarify which takes precedence

Fix It: Add: "If there are different caps for different types of claims, extract the general liability cap. If there is no general cap but only specific caps (e.g., for IP, confidentiality), extract the highest specific cap."

Common Failure Patterns & Solutions

Quality Assurance Checklist

Before finalizing a description, verify:

• Tested on at least 5 diverse contracts
• Extraction accuracy >75% on test set
• Output format is consistent
• Edge cases are handled
• Party roles are unambiguous
• Alternative terminology is covered
• Section locations are specified
• Amendment handling is addressed
• AI Explanation makes sense
• Team members can understand the description

5. Troubleshooting Common Issues

Issue: AI Keeps Extracting from Wrong Section

Symptom: AI finds the term in Definitions or Recitals instead of operative clauses

Solution: Add to description: "Do NOT extract from the Definitions, Recitals, or 'WHEREAS' clauses. Look for the operative provision in the body of the agreement."

Issue: AI Misses Information in Exhibits/Schedules

Symptom: Core data is in exhibits but AI only searches main agreement

Solution: Add to description: "This information may be found in Exhibit A, Schedule 1, or an attached Order Form. Be sure to check all exhibits and schedules, not just the main agreement."

Issue: Inconsistent Results Across Similar Contracts

Symptom: Same contract type giving different results

Causes:

• Templates evolved over time (old vs. new versions)
• Different drafters used different terminology
• Some contracts use non-standard formats

Solution:

• Review 5-10 contracts to identify variations
• List possible alternative phrasings in description
• Create separate metadata fields for substantially different templates

Issue: AI Hallucinates Values

Symptom: AI provides plausible but incorrect values

Common Scenarios:

• Infers implied obligations not stated
• Calculates values that should be extracted
• Makes assumptions about missing information

Solution: Add to description: "Only extract explicitly stated values. If the value must be calculated or inferred, output 'Not stated'. Do NOT make assumptions."

Issue: Multi-Party Contracts Cause Confusion

Symptom: Three-way agreements (e.g., Customer, Vendor, End User)

Solution: Expand party identification: "Extract the liability cap of the Vendor (also called 'Service Provider' or 'Company') to the direct Customer (also called 'Client' or 'Purchaser'). Do NOT include caps related to End Users, Subcontractors, or third-party beneficiaries unless they directly affect Vendor-Customer liability."

Issue: Conditional Clauses Create Ambiguity

Symptom: "If X then Y, otherwise Z" provisions confuse AI

Example: "If contract value >$100K, notice period is 90 days; otherwise 30 days"

Solution: Create separate conditional fields:

• Field 1: "Notice Period (High Value)" - for contracts >$100K
• Field 2: "Notice Period (Standard)" - for contracts ≤$100K OR use calculation logic in your systems post-extraction

Issue: Date Calculations Wrong

Symptom: Expiration Date extracted incorrectly when calculated from Effective Date + Term

Solution: Add: "Extract the explicitly stated Expiration Date or End Date. Do NOT calculate by adding the term to the effective date - find the actual stated expiration date in the contract."

Issue: Currency Conversion Confusion

Symptom: Contracts in mixed currencies

Solution: Add: "If the amount is in a currency other than USD, extract the amount in its original currency. Note the currency in the AI Explanation. Do NOT attempt to convert to USD."

Issue: Gradual Degradation Over Time

Symptom: Descriptions that worked well start performing worse

Causes:

• Contract templates changed
• New contract types introduced
• Company terminology evolved
• New amendments or riders added

Solution:

• Schedule quarterly description reviews
• Update descriptions when templates change

6. Specific Examples by Contract Type

7. Advanced Techniques for Power Users

Technique 1: Using AI Explanation for Data Enrichment

You can instruct the AI to put additional context in the explanation field that you can parse programmatically.

Example: "Extract the termination notice period in days. In the AI Explanation, output the specific contract reference in this format: 'REFERENCE: Section [X], Clause [Y]'."

Use Case: Building citation databases or audit trails

Technique 2: Extraction with Confidence Levels

For critical fields, ask the AI to express certainty.

Example: "Extract the liability cap amount. In the AI Explanation, start with 'CONFIDENCE: HIGH' if explicitly stated, 'CONFIDENCE: MEDIUM' if implied from context, or 'CONFIDENCE: LOW' if ambiguous or inferred."

Use Case: Flagging items that need manual review

Technique 3: Multi-Field Validation Logic

Use AI Explanation to validate related fields.

Example (for Expiration Date field): "Extract the contract expiration date. In the AI Explanation, also state the Effective Date and Term Length you found, so we can verify: Expiration Date = Effective Date + Term Length."

Use Case: Quality assurance and error detection

Technique 4: Handling Tables and Schedules

For fields that reference complex tables.

Example: "Extract the Year 1 total fees from the Pricing Schedule (typically Exhibit A or Schedule 1). This may be presented as a table with columns like 'Year', 'Subscription Fee', 'Support Fee', etc. Sum all Year 1 fees excluding one-time setup costs. If the table uses fiscal years instead of calendar years, extract Fiscal Year 1. In the AI Explanation, specify which exhibit and which rows were summed."

Use Case: Complex pricing extractions

Technique 5: Jurisdictional Variations

When contracts have jurisdiction-specific provisions.

Example: "Extract the applicable data privacy law. Look for references to GDPR, CCPA, PIPEDA, LGPD, or other data protection regulations. If multiple apply based on geography, list all separated by semicolons. If no specific law is mentioned but the contract refers to 'applicable data protection laws', output 'General - [Governing Law Jurisdiction]' using the jurisdiction from the Governing Law clause."

Use Case: Multi-jurisdictional compliance tracking

Technique 6: Amendment Reconciliation

For complex amendment scenarios.

Example: "Extract the current liability cap including all amendments. Start with Schedule A of the original agreement dated [DATE]. Then check for Amendment No. 1 (dated [DATE]), Amendment No. 2 (dated [DATE]), etc. Use the most recent amendment value. In the AI Explanation, specify: 'Original value: $X [from Document Y], Modified by Amendment No. Z to: $A'."

Use Case: Contract amendment audit trails

Technique 7: Negation Handling

When presence vs. absence is critical.

Example: "Determine if there is a Most Favored Customer clause. Output 'Yes' ONLY if there is explicit language guaranteeing the customer pricing equal to or better than any other customer. Output 'No' if no such clause exists or if pricing protection is limited (e.g., 'within same industry' or 'same sized customers'). Look for phrases like 'most favored', 'pricing parity', 'best pricing', or 'no less favorable terms'."

Use Case: Identifying high-risk contractual commitments

8. Quick Reference Guide

Sample Description Template

[WHAT]: The specific information to extract

[WHERE]: Typically found in [Section Name] or [Exhibit X]. May also be labeled as "[Alternative Term 1]" or "[Alternative Term 2]"

[HOW]: Output as [format] (e.g., [example])

[EDGE CASES]:

If [scenario 1], output [value 1]

If [scenario 2], output [value 2]

If not found or ambiguous, output [default value]

[VALIDATION]: In the AI Explanation, include [validation info]

Common Patterns Library

Liability Caps: "The maximum amount [PARTY] is liable to pay [OTHER PARTY] for [CLAIM TYPE]. Typically in 'Limitation of Liability' section. Output as number only. If uncapped/unlimited, output '0'. If multiple caps exist, extract [specify which]."

Notice Periods: "The number of days advance written notice required from [PARTY] to [ACTION]. Output in days only. If in months, convert (assume 30 days/month). If 'immediate' or 'upon receipt', output '0'."

Party Names: "The full legal name of [ROLE PARTY] as stated in the preamble or signature block, including entity type (Inc., LLC, Ltd.). Also referred to as '[ALTERNATIVE TERM]' in the agreement. Output without address or jurisdiction."

Dates: "The [DATE TYPE] as explicitly stated in [LOCATION]. NOT the [OTHER DATE TYPE]. Format: MM/DD/YYYY. If only month/year, use [last/first] day of month."

Renewal Terms: "Whether the agreement [RENEWAL BEHAVIOR]. Output 'Yes' if [CONDITION FOR YES]. Output 'No' if [CONDITION FOR NO]. Look for phrases like '[COMMON PHRASINGS]'."

8. Using "Generate Description" or "Enhance Description"

As a starting point, the "Generate Description" button can be helpful for creating your descriptions. It automatically generates a description based on the contract type, metadata type, and label. However:

• AI-generated descriptions are more generic and may not work well for unique or complex metadata fields.
• Sometimes, AI-generated descriptions miss the point or phrase the question differently than intended.

Instead, to ensure better descriptions are created, you can start off with a simple draft in plain english, and use the "Enhance Description" button. This will convert your description into something more suitable for the AI to understand. Manually adding information specific to your context, and letting the "Enhance Description" functionality take over the rest is the best way to make use of this feature. This specific information may look like:

• Any examples that might be relevant. For ex: "Liability cap is $10,000"
• Any special format instructions. For ex: "Capture the number of rooms in the format Room Type: Room Quantity"
• Any hints or cues to where such data might be found in the contract. For ex: "The Liability Cap might be found in the Limitation of Liability Section in the contract"