document-tools

name	document-tools
description	Read, summarize, extract key data, and simplify medical documents for patients. Use when user asks to read a document, summarize a file, extract data from a report, parse health records, or simplify medical jargon. Supports patient-friendly mode that converts complex medical terms into plain language. Triggers on: read my, summarize, extract from, parse this, explain this report, simplify, what does this mean, medical terms, translate to plain language, patient-friendly.
allowed-tools	["read","glob","bash","write"]
version	1.0.0

Document Tools

Read, summarize, extract key data, and simplify medical documents for patients.

When to Use

• User asks to "read my health report"
• User asks to "summarize this document"
• User asks to "extract data from X"
• User asks to "explain this in simple terms"
• User asks "what does this medical report mean?"
• User provides a file path and asks for analysis
• User wants patient-friendly explanation of medical jargon

Supported Formats

Format	How to Read	Notes
.md	Use read tool	Frontmatter + body
.json	Use read tool	Structured data
.txt	Use read tool	Plain text
.pdf	Use bash + pdftotext	Requires pdftotext

Execution Steps

Step 1: Locate the File

Use glob to find the file:

glob "**/thyroid*.md"
glob "**/2026*.md"

Step 2: Read the Content

read --path "/path/to/file.md"

Step 3: Determine Output Mode

User Request	Mode	Description
"Summarize" / "Extract"	Technical	Key fields, structured data
"Explain" / "Simplify"	Patient-Friendly	Plain language, visual aids
"What does this mean?"	Patient-Friendly	Focus on interpretation

Step 4A: Technical Mode (Default)

Extract key fields for health documents:

• Date of examination/report
• Key measurements (numbers + units)
• Classifications (TI-RADS, BI-RADS, etc.)
• Doctor's conclusion/impression
• Recommendations

Output format:

{
  "source": "path/to/file.md",
  "date": "YYYY-MM-DD",
  "extracted_fields": {
    "measurement": "value",
    "classification": "category",
    "conclusion": "doctor's note"
  },
  "summary": "2-3 sentence summary"
}

Step 4B: Patient-Friendly Mode (Enhanced)

Convert complex medical documents into easy-to-understand format:

Medical Term Simplification

Medical Term	Plain Language
Hypertension	High blood pressure
Hyperglycemia	High blood sugar
Benign	Not cancer, harmless
Malignant	Cancerous
Nodule	Small lump or bump
Lesion	Area of damaged tissue
Edema	Swelling from fluid
Erythema	Redness of skin
Bilateral	On both sides
Unilateral	On one side
Diffuse	Spread out, not in one spot
Focal	In one specific area
Acute	Sudden, recent onset
Chronic	Long-lasting, ongoing
Asymptomatic	No symptoms
Prognosis	Expected outcome
Differential diagnosis	Possible causes being considered
CBC (Complete Blood Count)	Blood cell count test
BMP/CMP (Basic/Comprehensive Metabolic Panel)	Blood chemistry test
HbA1c	Average blood sugar over 3 months
TSH	Thyroid function test
WBC	White blood cell count
RBC	Red blood cell count
PLT	Platelet count (blood clotting)

Visual Summary Format

📋 Medical Report Summary (Patient-Friendly)

🏥 What Was Tested:
[Plain language description of the test]

📊 Results at a Glance:
┌────────────────────────────────────────────────┐
│ Normal:        ✅ ✅ ✅ ⚠️ ✅                    │
│ Needs Attention: ⚠️ [1 item]                   │
└────────────────────────────────────────────────┘

🔍 Key Findings:
1. ✅ [Normal finding] - This means [explanation]
2. ⚠️ [Abnormal finding] - This means [explanation]
3. ✅ [Normal finding] - This means [explanation]

💡 What This Means for You:
[2-3 sentences explaining the overall significance]

⚠️ Important Notes:
[Any warnings or things to watch for]

❓ Questions to Ask Your Doctor:
1. [Relevant question based on findings]
2. [Follow-up question if needed]

📅 Next Steps:
- [Recommended action]
- [Follow-up timing]

Severity Indicators

Status	Icon	Meaning
Normal	✅	Within healthy range
Borderline	⚠️	Slightly outside normal, monitor
Abnormal	🔶	Outside normal range, follow up
Critical	🔴	Urgent attention needed

Common Health Document Patterns

Blood Test Results

Technical extraction:

• Date, values outside normal range, doctor's note

Patient-friendly output:

🩸 Blood Test Results (March 2, 2026)

✅ Good News:
- White blood cells: Normal (fighting infection well)
- Red blood cells: Normal (carrying oxygen well)
- Platelets: Normal (blood clotting fine)

⚠️ Items to Discuss:
- Blood sugar: Slightly high (105 mg/dL)
  → Normal is under 100 mg/dL
  → Suggestion: Reduce sugary foods, retest in 3 months

📊 Overall: Generally healthy, one minor item to watch

Ultrasound Report

Technical extraction:

• Date, organ, measurements, classification, conclusion

Patient-friendly output:

🔬 Ultrasound Report Summary

📍 What Was Checked: [Organ]

📏 Size Found: [X] × [Y] × [Z] mm
   → About the size of a [common object comparison]

📊 Risk Category: [TI-RADS/BI-RADS] [Number]
   → This means: [plain language explanation]
   → Likelihood of being cancerous: [X]%

👨‍⚕️ Doctor's Opinion: [Simplified conclusion]

💡 What You Should Know:
- [Key point 1]
- [Key point 2]

📅 Follow-Up: [Simplified recommendation]

Radiology Report

Patient-friendly output:

📷 Imaging Report Summary

🔍 What Was Scanned: [Body part]

📋 What They Found:
1. [Finding 1 in plain language]
2. [Finding 2 in plain language]

⚠️ Attention Needed:
- [Any concerning findings explained simply]

✅ Normal Findings:
- [List of normal results]

💡 Bottom Line:
[2-3 sentence overall assessment]

Output Format

Technical Mode

{
  "source": "path/to/file.md",
  "date": "YYYY-MM-DD",
  "type": "report_type",
  "extracted_fields": {},
  "summary": "Technical summary"
}

Patient-Friendly Mode

# [Report Type] — Simplified Summary

[Visual summary in plain language]

---
⚠️ This is a simplified interpretation for educational purposes only. 
Always discuss results with your healthcare provider.

Privacy Note

• All processing is local
• No external transmission of document content
• Results stored in health/References/ locally

Error Handling

• File not found → Ask user for correct path
• Unsupported format → Suggest converting to .md
• Empty file → Report empty, suggest checking source
• Complex jargon → Use medical dictionary to explain

---

Version: 2.0.0 Updated: 2026-03-21 New in v2.0: Patient-friendly simplification mode, medical term translation Inspired by: OpenClaw Medical Skills patiently-ai (MIT License)