document-tools

# 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: ```bash glob "**/thyroid*.md" glob "**/2026*.md" ``` ### Step 2: Read the Content ```bash 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:** ```json { "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 ```json { "source": "path/to/file.md", "date": "YYYY-MM-DD", "type": "report_type", "extracted_fields": {}, "summary": "Technical summary" } ``` ### Patient-Friendly Mode ```markdown # [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)