Skill: moclippa/gevety (version 1.12.0)

--- name: gevety version: 1.11.0 description: Access your Gevety health data - biomarkers, healthspan scores, biological age, what-if scenarios across bio-age clocks, biomarker trajectories, bio-age clock history, non-clock health signals (CRF / stress resilience), supplements, medications, medical profile, activities, strength training, erg results, daily actions, 90-day health protocol, upcoming tests, lab reports, health documents, clinical findings, and health content homepage: https://gevety.com user-invocable: true command: gevety metadata: clawdbot: primaryEnv: GEVETY_API_TOKEN requires: env: - GEVETY_API_TOKEN --- # Gevety Health Assistant You have access to the user's health data from Gevety via the REST API. Use `web_fetch` to retrieve their biomarkers, healthspan scores, and wearable statistics. ## First-Time Setup If this is the user's first time using Gevety, guide them through setup: 1. **Get a Gevety account**: Sign up at https://gevety.com if they don't have one 2. **Upload blood tests**: They need to upload lab reports to have biomarker data 3. **Generate an API token**: - Go to https://gevety.com/settings - Click "Developer API" tab - Click "Generate Token" - Copy the token (starts with `gvt_`) 4. **Configure Clawdbot**: Add the token to `~/.clawdbot/clawdbot.json`: ```json { "skills": { "entries": { "gevety": { "apiKey": "gvt_your_token_here" } } } } ``` After adding the token, they'll need to restart Clawdbot for changes to take effect. ## Authentication All requests require Bearer authentication. Use the `GEVETY_API_TOKEN` environment variable: ``` Authorization: Bearer $GEVETY_API_TOKEN ``` Base URL: `https://api.gevety.com` ## Biomarker Name Handling The API preserves biomarker specificity. Fasting and non-fasting variants are distinct: | Input Name | API Returns | Notes | |------------|-------------|-------| | CRP, C-Reactive Protein | **CRP** or **C-Reactive Protein** | Standard CRP (LOINC 1988-5) | | hsCRP, hscrp, Cardio CRP | **hs-CRP** | High-sensitivity CRP (LOINC 30522-7) | | Glucose, Blood Glucose | **Glucose** | Generic/unspecified glucose | | Fasting Glucose, FBS, FBG | **Glucose Fasting** | Fasting-specific glucose | | Insulin, Serum Insulin | **Insulin** | Generic/unspecified insulin | | Fasting Insulin | **Insulin Fasting** | Fasting-specific insulin | | IG | **Immature Granulocytes** | Expanded for clarity | | Vitamin D, 25-OH Vitamin D | **Vitamin D** | | | LDL, LDL Cholesterol | **LDL Cholesterol** | | **Important**: The API no longer forces fasting assumptions. If a lab report says "Glucose" without specifying fasting, it returns as "Glucose" (not "Fasting Glucose"). This preserves the original context from your lab results. ## Available Endpoints ### 1. List Available Data (Start Here) **Always call this first** to discover what health data exists. ``` GET /api/v1/mcp/tools/list_available_data ``` Returns: - `biomarkers`: List of tracked biomarkers with test counts and latest dates - `wearables`: Connected devices and available metrics - `insights`: Whether healthspan score is calculated, axis scores available - `data_coverage`: Percentage of recommended biomarkers tracked (0-100) ### 2. Get Health Summary Overview of the user's health status. ``` GET /api/v1/mcp/tools/get_health_summary ``` Returns: - `overall_score`: Healthspan score (0-100) - `overall_status`: OPTIMAL, GOOD, SUBOPTIMAL, or NEEDS_ATTENTION - `trend`: IMPROVING, STABLE, or DECLINING - `axis_scores`: Scores for each health dimension (metabolic, cardiovascular, etc.) - `top_concerns`: Biomarkers needing attention - `scoring_note`: Explanation when overall score differs from axis scores (e.g., "Overall healthspan is high, but Inflammation axis needs attention") **Note on scores**: The overall healthspan score is a weighted composite. It's possible to have a high overall score while one axis is low (or vice versa). The `scoring_note` field explains these situations. ### 3. Query Biomarker Get detailed history for a specific biomarker. ``` GET /api/v1/mcp/tools/query_biomarker?biomarker={name}&days={days} ``` Parameters: - `biomarker` (required): Name or alias (e.g., "vitamin d", "ldl", "hba1c", "crp") - `days` (optional): History period, 1-730, default 365 Returns: - `canonical_name`: Standardized biomarker name (see table above) - `history`: Array of test results with dates, values, units, flags - `latest`: Most recent result - `trend`: Direction (IMPROVING, STABLE, DECLINING) and percent change - `optimal_range`: Evidence-based optimal values **Tip**: If biomarker not found, the response includes `did_you_mean` suggestions. ### 4. Get Wearable Stats Daily metrics from connected wearables (Garmin, Oura, Whoop, etc.). ``` GET /api/v1/mcp/tools/get_wearable_stats?days={days}&metric={metric} ``` Parameters: - `days` (optional): History period, 1-90, default 30 - `metric` (optional): Focus on specific metric (steps, hrv, sleep, etc.) Returns: - `connected_sources`: List of connected wearable platforms - `daily_metrics`: Per-day data (steps, resting HR, HRV, sleep, recovery) - `summaries`: Aggregated stats with averages, min, max, trends ### 5. Get Opportunities Get ranked health improvement opportunities with estimated healthspan impact. ``` GET /api/v1/mcp/tools/get_opportunities?limit={limit}&axis={axis} ``` Parameters: - `limit` (optional): Max opportunities to return, 1-50, default 10 - `axis` (optional): Filter by health axis (metabolic, cardiovascular, etc.) Returns: - `opportunities`: Ranked list of improvement opportunities - `total_opportunity_score`: Total healthspan points available - `total_years_estimate`: Estimated years of healthy life if all optimized - `healthspan_score`: Current healthspan score Each opportunity includes: - `biomarker`: Standardized biomarker name - `current_value` / `optimal_value`: Where you are vs target - `opportunity_score`: Healthspan points gained if optimized - `years_estimate`: Estimated healthy years gained - `priority`: Rank (1 = highest impact) ### 6. Get Biological Age Calculate biological age using validated algorithms (PhenoAge, Light BioAge). ``` GET /api/v1/mcp/tools/get_biological_age ``` Returns: - `result`: Biological age calculation (if available) - `biological_age`: Calculated biological age - `chronological_age`: Calendar age - `age_acceleration`: Difference (positive = aging faster) - `algorithm`: Which algorithm was used - `biomarkers_used`: Biomarkers that contributed - `interpretation`: What the result means - `available`: Whether calculation was possible - `reason`: Why not available (if applicable) - `upgrade_available`: Can unlock better algorithm with more data - `upgrade_message`: What additional tests would help ### 6c. Get Biomarker Trajectory (Linear Regression on User History) Get a biomarker's trajectory: slope, direction, 3/6-month predictions, time-to-target, and a freshness flag. Linear regression on the user's history. ``` GET /api/v1/mcp/tools/get_biomarker_trajectory?biomarker={name}&months={int} ``` Parameters: - `biomarker` (required): canonical name or alias (e.g., 'LDL Cholesterol' or 'ldl') - `months` (optional): history window in months (default 12, min 3, max 36) Returns: - `direction`: improving | worsening | stable (relative to functional / reference range) - `slope_per_month`, `predicted_3m`, `predicted_6m` - `time_to_target_months` when improving toward target - `confidence_r_squared` (R²) — accuracy depends on data point density - `freshness`: fresh (≤180d) / aging (≤365d) / stale (>365d) - `evidence_tier: 'directional'` (linear regression on user history, NOT a validated population trajectory model) - `caveats[]`: low-fit and stale-data flags Returns `supported=false` with `status="insufficient_data"` when fewer than 3 data points fall in the window — explain that to the user rather than treating it as an error. ### 6d. Get Clock History (Per-Panel Bio-Age History) Per-panel bio-age history across PhenoAge / Light BioAge / Vascular Age. Each panel evaluated against ONLY that panel's biomarkers (chronological age uses the panel's draw date) for an honest snapshot of bio-age across time. ``` GET /api/v1/mcp/tools/get_clock_history?clock={...}&months={int} ``` Parameters: - `clock` (optional): `phenoage` | `light_bioage` | `vascular` | `all` (default `all`) - `months` (optional): history window (default 24, min 6, max 120) Returns per-clock blocks each carrying: - `panels[]`: per-panel `test_date` / `chronological_age` / `biological_age` / `delta_years` - `trend`: improving | worsening | stable (across panels) - `delta_years_change`: oldest → newest delta_years change (negative = trending younger) - `evidence_tier`: validated (PhenoAge / Vascular) | validated_emerging (Light BioAge) - `freshness`: fresh / aging / stale based on latest panel - `caveats[]` Returns `supported=false` with `status="no_panels_in_window"` when a clock has no qualifying panels in the window. ### 6e. Get Health Signal (Non-Clock Signals) Generic accessor for non-clock health signals. All v1 signals carry `evidence_tier='directional'` — strong biomarker→outcome literature but expressed as a score/index, not validated population-model years. ``` GET /api/v1/mcp/tools/get_health_signal?signal={crf|stress_resilience} ``` Supported signals (v1): - `crf`: Cardiorespiratory fitness (VO2max + FRIEND percentile + Mandsager 2018 mortality risk class) - `stress_resilience`: 0-100 composite from HRV/RHR trends, recovery score, sleep efficiency, cortisol:DHEA-S ratio (MAI-7 scorer) Returns `score` / `value` / `category` / `breakdown[]` / `freshness` / `caveats` with structured `supported=false` cases for missing data, missing baseline, or fewer than the minimum required signals. ### 6b. Compute What-If (Multi-Biomarker Scenario Simulator) Simulate the impact of biomarker target changes across PhenoAge, Light BioAge, and Vascular Age clocks. Joint compute via each clock's native recompute path — NOT a naive sum of single-biomarker effects. ``` POST /api/v1/mcp/tools/compute_what_if Content-Type: application/json { "targets": [ { "biomarker": "ldl_cholesterol", "target_value": 80, "target_unit": "mg/dL" }, { "biomarker": "hdl_cholesterol", "target_value": 60, "target_unit": "mg/dL" } ], "clocks": ["phenoage", "light_bioage", "vascular"] } ``` Body: - `targets` (1-9 entries, required): Target overrides per biomarker. - `biomarker`: Canonical key (snake_case) — supports `ldl_cholesterol`, `hdl_cholesterol`, `total_cholesterol`, `systolic_bp`, `glucose`, `hscrp`, `albumin`, `creatinine`, `alkaline_phosphatase`, `rdw`, `mcv`, `wbc`, `lymphocyte_percent`. Aliases auto-resolve: `LDL`, `HDL`, `TC`, `SBP`, `ALP`, `hsCRP`. ApoB is recognized but no v1 clock consumes it. HbA1c is NOT a v1 input. - `target_value`: Hypothetical value. - `target_unit` (optional): Defaults to canonical unit (mg/dL for chol, mmHg for SBP, etc.). - `clocks` (optional): Defaults to `[phenoage, light_bioage, vascular]`. GrimAge2 / DunedinPACE return `supported=false` with `status="evidence_gated"` until methylation data is connected. Returns: - `scenario`: Echo of the canonicalized request. - `baseline`: User chronological age + UTC computation timestamp. - `clocks[]`: One row per requested clock with: - `name`, `algorithm`, `evidence_tier` (`validated` / `validated_emerging`), `model_provenance`, `supported` - When supported: `direction` (`younger` / `older` / `unchanged`), `current_value`, `scenario_value`, `delta_years`, `applied_targets`, `missing_targets[]` (with structured reason keys), `model_assumptions[]` (e.g., the LDL → ΔTotal Cholesterol derivation rule for Vascular Age), `freshness`, `caveats[]` - When not supported: `status` (`evidence_gated` / `requires_more_data` / `missing_baseline` / `out_of_range`) + `reason` - `summary`: - `best_clock`: Highest-evidence supported clock with applied targets - `per_clock_deltas`: Structured array — pick what to surface - `ranked_levers`: Per-target leave-one-out approximation - `joint_caveat`: "deltas are NOT additive across clocks — different inputs" - `non_additivity_warning`: ranked_levers contributions don't sum exactly to a clock's total delta because of non-linear interactions - `guardrails`: `is_medical_advice: false` + user-facing disclaimer. Use this to answer "what happens to my biological age clocks if my LDL drops to 80 and HDL rises to 60?". ### 7. List Supplements Get the user's supplement stack. ``` GET /api/v1/mcp/tools/list_supplements?active_only={true|false} ``` Parameters: - `active_only` (optional): Only show currently active supplements, default false Returns: - `supplements`: List of supplements with dosage, frequency, duration - `active_count`: Number of currently active supplements - `total_count`: Total supplements tracked Each supplement includes: - `name`: Supplement name - `dose_text`: Formatted dosage (e.g., "1000 mg daily", "200mg EPA + 100mg DHA daily") - `is_active`: Currently taking - `duration_days`: How long on this supplement **Note**: For multi-component supplements (like fish oil), `dose_text` shows all components (e.g., "200mg EPA + 100mg DHA daily"). ### 8. Get Activities Get workout/activity history from connected wearables. ``` GET /api/v1/mcp/tools/get_activities?days={days}&activity_type={type} ``` Parameters: - `days` (optional): History period, 1-90, default 30 - `activity_type` (optional): Filter by type (running, cycling, strength, etc.) Returns: - `activities`: List of workouts with metrics - `total_count`: Number of activities - `total_duration_minutes`: Total workout time - `total_distance_km`: Total distance covered - `total_calories`: Total calories burned Each activity includes: - `activity_type`: Type (running, cycling, swimming, etc.) - `name`: Activity name - `start_time`: When it started - `duration_minutes`: How long - `distance_km`: Distance (if applicable) - `calories`: Calories burned - `avg_hr` / `max_hr`: Heart rate data - `source`: Where the data came from (garmin, strava, hevy, concept2, etc.) - `elevation_gain_m`: Elevation gain in meters (outdoor activities) - `avg_pace_min_per_km`: Average running pace - `avg_watts`: Average cycling power - `strain_score`: Whoop strain (0-21) - `avg_cadence`: Cadence (RPM or steps/min) - `is_indoor`: Indoor activity flag - `total_volume_kg`: Total weight lifted (Hevy strength workouts) - `exercise_count`: Number of exercises (Hevy) - `set_count`: Number of sets (Hevy) - `pace_500m`: Pace per 500m (Concept2 erg sessions) - `stroke_rate`: Strokes per minute (Concept2) - `machine_type`: Erg machine type — rower, skierg, bikerg (Concept2) **Note**: Source-specific fields (volume, pace, stroke rate, etc.) are only populated for the relevant source. For example, `total_volume_kg` only appears on Hevy activities and `pace_500m` only on Concept2 activities. ### 9. Get Today's Actions Get the user's action checklist for today. ``` GET /api/v1/mcp/tools/get_today_actions?timezone={timezone} ``` Parameters: - `timezone` (optional): IANA timezone (e.g., "America/New_York"), default UTC Returns: - `effective_date`: The date being queried in user's timezone - `timezone`: Timezone used for calculation - `window_start` / `window_end`: Day boundaries (ISO datetime) - `actions`: List of today's actions - `completed_count` / `total_count`: Completion stats - `completion_pct`: Numeric completion percentage (0-100) - `last_updated_at`: Cache staleness indicator Each action includes: - `action_id`: Stable ID for deep-linking - `title`: Action title - `action_type`: Type (supplement, habit, diet, medication, test, procedure) - `completed`: Whether completed today - `scheduled_window`: Time window (morning, afternoon, evening, any) - `dose_text`: Dosage info if applicable (e.g., "1000 mg daily") ### 10. Get Protocol Get the user's 90-day health protocol with top priorities. ``` GET /api/v1/mcp/tools/get_protocol ``` Returns: - `protocol_id`: Stable protocol ID - `phase`: Current phase (week1, month1, month3) - `days_remaining`: Days until protocol expires - `generated_at` / `last_updated_at`: Timestamps - `top_priorities`: Top 5 health priorities with reasoning - `key_recommendations`: Diet and lifestyle action items - `total_actions`: Total actions in protocol Each priority includes: - `priority_id`: Stable ID (same as rank) - `rank`: Priority rank (1 = highest) - `biomarker`: Standardized biomarker name - `status`: Current status (critical, concerning, suboptimal, optimal) - `target`: Target value with unit - `current_value` / `unit`: Current measured value - `measured_at`: When this biomarker was last measured - `why_prioritized`: Explanation for why this is prioritized **Note**: If no protocol exists, returns a helpful error with suggestion to generate one at gevety.com/protocol. ### 11. Get Upcoming Tests Get tests that are due or recommended based on biomarker history and AI recommendations. ``` GET /api/v1/mcp/tools/get_upcoming_tests ``` Returns: - `tests`: List of upcoming tests sorted by urgency - `overdue_count`: Number of overdue tests - `due_soon_count`: Tests due within 30 days - `recommended_count`: AI-recommended tests - `total_count`: Total number of upcoming tests Each test includes: - `test_id`: Stable ID for deep-linking (format: `panel_{id}` or `recommended_{id}`) - `name`: Test or panel name - `test_type`: Type (panel, biomarker, recommended) - `urgency`: Priority level (overdue, due_soon, recommended) - `due_reason`: Why this test is needed (e.g., "Due 2 weeks ago", "AI recommendation") - `last_tested_at`: When this was last tested (if applicable) - `biomarkers`: List of biomarkers included (for panels) ### 12. List Test Results Get a list of uploaded lab reports with dates, source, and biomarker count. ``` GET /api/v1/mcp/tools/list_test_results?limit={limit}&start_date={date}&end_date={date} ``` Parameters: - `limit` (optional): Max reports to return, 1-50, default 10 - `start_date` (optional): Filter from date (YYYY-MM-DD) - `end_date` (optional): Filter to date (YYYY-MM-DD) Returns: - `reports`: List of lab reports - `total_reports`: Total number of reports Each report includes: - `report_id`: Stable report ID - `report_date`: Date of the lab test - `source`: How it was uploaded (pdf, email, manual) - `lab_name`: Laboratory name (if available) - `biomarker_count`: Number of biomarkers in this report - `filename`: Original filename (if uploaded as PDF) ### 13. List All Biomarkers Get ALL tracked biomarkers with current value, status classification, and trend in one call. ``` GET /api/v1/mcp/tools/list_all_biomarkers?category={category}&status={status} ``` Parameters: - `category` (optional): Filter by category (e.g., "metabolic", "cardiovascular") - `status` (optional): Filter by status (optimal, suboptimal, high, low, critical_high, critical_low) Returns: - `biomarkers`: List of all biomarkers with latest values - `total_count`: Total number of biomarkers - `counts_by_status`: Breakdown by status (optimal, suboptimal, high, low, critical_high, critical_low, unknown) Each biomarker includes: - `name`: Standardized biomarker name - `category`: Health category (metabolic, cardiovascular, etc.) - `latest_value`: Most recent test value - `unit`: Measurement unit - `status`: Classification (optimal, suboptimal, high, low, critical_high, critical_low, unknown) - `last_test_date`: When this was last tested - `trend_direction`: Trend since previous test (increasing, decreasing, stable) ### 14. Get Content Recommendations Get personalized health content recommendations based on biomarker profile. ``` GET /api/v1/mcp/tools/get_content_recommendations?limit={limit}&category={category} ``` Parameters: - `limit` (optional): Max recommendations, 1-20, default 5 - `category` (optional): Filter by content category Returns: - `recommendations`: List of recommended articles - `total_available`: Total recommendations available Each recommendation includes: - `content_id`: Stable content ID - `title`: Article title - `summary`: Brief summary - `category`: Content category - `relevance_reason`: Why this is relevant to the user - `quality_score`: Evidence quality score (only high-quality content is shown) - `url`: Link to the article ### 15. Get Strength Training Get detailed strength training data from Hevy (workouts, volume, muscle distribution). ``` GET /api/v1/mcp/tools/get_strength_training?days={days}&muscle_group={group} ``` Parameters: - `days` (optional): History period, 1-90, default 30 - `muscle_group` (optional): Filter by muscle group (e.g., "chest", "back", "legs") Returns: - `workouts`: List of strength workouts with exercises, sets, and volume - `total_workouts`: Total workout count - `total_volume_kg`: Total weight lifted - `avg_sessions_per_week`: Training frequency - `muscle_distribution`: Volume breakdown by muscle group (with percentages) - `weekly_volume`: Weekly volume trend data Each workout includes: - `started_at`: When the workout started - `duration_minutes`: Workout duration - `total_volume_kg`: Total volume for this workout - `exercise_count` / `set_count`: Number of exercises and sets - `exercises`: Detailed exercise list with name, muscle group, sets, top set weight, total volume, total reps - `enrichment_source`: If enriched with HR data from another wearable (garmin, strava, etc.) - `enrichment_avg_hr`: Average HR from enrichment source **Note**: Requires Hevy connection. Returns error if user has no Hevy integration. ### 16. Get Erg Results Get Concept2 ergometer results (rowing, skiing, biking). ``` GET /api/v1/mcp/tools/get_erg_results?days={days}&machine_type={type} ``` Parameters: - `days` (optional): History period, 1-90, default 30 - `machine_type` (optional): Filter by machine — rower, skierg, bikerg Returns: - `sessions`: List of erg sessions with detailed metrics - `total_sessions`: Total session count - `total_meters`: Total distance - `total_time_seconds`: Total time on erg - `avg_pace_formatted`: Overall average pace per 500m (e.g., "2:05.3") - `machines`: Per-machine summary (session count, total meters, avg pace) - `weekly_volume`: Weekly volume trend data Each session includes: - `date`: Session date - `machine_type`: rower, skierg, or bikerg - `distance_meters`: Distance in meters - `time_seconds`: Duration in seconds - `pace_500m`: Pace per 500m formatted (e.g., "2:05.3") - `calories`: Calories burned - `stroke_rate`: Average strokes per minute - `avg_hr`: Average heart rate (if available) - `drag_factor`: Erg drag factor setting **Note**: Requires Concept2 connection. Returns error if user has no Concept2 integration. ### 17. List Medications Get the user's prescription medications. ``` GET /api/v1/mcp/tools/list_medications?active_only={true|false} ``` Parameters: - `active_only` (optional): Only show currently active medications, default true Returns: - `medications`: List of medications with dosage, frequency, route, and reason - `active_count`: Number of currently active medications - `total_count`: Total medications tracked Each medication includes: - `name`: Medication name (brand) - `generic_name`: Generic/active ingredient name - `dosage`: Dosage (e.g., "500mg") - `frequency`: How often taken (e.g., "twice daily") - `route`: Route of administration (oral, topical, injection, etc.) - `is_active`: Currently taking - `start_date` / `end_date`: When started/stopped - `duration_days`: How long on this medication - `reason`: Why prescribed (auto-decrypted from encrypted storage) ### 18. Get Medical Profile Get the user's medical profile including conditions, allergies, family history, and health goals. ``` GET /api/v1/mcp/tools/get_medical_profile ``` Returns: - `conditions`: List of medical conditions (active/managed) - `allergies`: List of allergies with severity and reaction type - `family_history`: Family medical history with relationships and onset ages - `goals`: Active health goals with priorities and target dates - `diet_type`: Current dietary pattern (if set) - `condition_count` / `allergy_count`: Summary counts Each condition includes: `name`, `status` (active/managed/resolved/monitoring), `severity`, `diagnosed` date, `notes` Each allergy includes: `allergen`, `severity` (mild/moderate/severe/life_threatening), `reaction_type` Each family history item includes: `condition`, `relationship` (father/mother/etc.), `age_at_onset`, `notes` ### 19. List Health Documents List all health documents including procedure reports, imaging, prescriptions, and more. ``` GET /api/v1/mcp/tools/list_health_documents?limit={limit}&document_type={type} ``` Parameters: - `limit` (optional): Max documents to return, 1-50, default 20 - `document_type` (optional): Filter by type (lab_report, procedure_report, imaging, prescription, doctor_note, other) Returns: - `documents`: List of health documents sorted by received date (newest first) - `total_count`: Total documents for this user - `by_type`: Breakdown of document counts by type Each document includes: - `document_id`: Document ID - `document_type`: Type (lab_report, procedure_report, imaging, etc.) - `document_subtype`: Subtype (cac, dexa, colonoscopy, mammogram, etc.) - `status`: Processing status (pending, processing, needs_review, extracted, archived) - `filename`: Original filename - `received_at`: When received (ISO format) - `ai_summary`: AI-generated summary of the document - `lab_name`: Lab name (for lab reports) - `test_date`: Test/procedure date **Note**: This goes beyond `list_test_results` which only shows lab reports. This includes ALL uploaded documents — procedure reports (CAC, DEXA, colonoscopy), imaging studies, prescriptions, and doctor notes. ### 20. Query Clinical Findings Get structured clinical findings extracted from health documents (imaging, procedures, etc.). ``` GET /api/v1/mcp/tools/query_clinical_findings?document_id={id}&category={cat}&search={text}&limit={limit} ``` Parameters: - `document_id` (optional): Filter by document ID (get IDs from `list_health_documents`) - `category` (optional): Filter by category (measurement, classification, finding, recommendation) - `search` (optional): Text search across finding text (e.g., "varicocele", "reflux", "volume") - `limit` (optional): Max findings to return, 1-100, default 50 Returns: - `findings`: List of structured clinical findings - `total_count`: Total findings matching query - `document_info`: Source document metadata (when filtering by document_id) Each finding includes: - `finding_id`: Finding ID - `document_id`: Source document ID - `finding_text`: Human-readable finding (e.g., "Left varicocele diameter supine rest 3.6 mm") - `category`: Type — measurement, classification, finding, or recommendation - `value`: Structured data object with applicable keys: - `number` + `unit`: Numeric measurements (e.g., 3.6 mm, 13.3 mL) - `laterality`: Left, right, or bilateral - `condition`: Context (e.g., "at rest", "on Valsalva", "standing") - `location`: Anatomical location - `grade` + `grade_system`: Grading (e.g., Grade III varicocele) - `present` / `absent`: Boolean findings (e.g., reflux present) - `confidence`: Extraction confidence 0.0-1.0 - `created_by`: Extraction source (universal, universal_procedure_extractor, cac_extractor, etc.) **This is the PRIMARY tool for accessing imaging and procedure report data.** Use it to answer questions about ultrasound findings, MRI results, procedure outcomes, or any non-lab health data. **Note**: Works alongside `list_health_documents` — first use `list_health_documents` to find document IDs, then `query_clinical_findings` to get the detailed findings. ## Interpreting Scores ### Healthspan Score (0-100) | Range | Status | Meaning | |-------|--------|---------| | 80-100 | OPTIMAL | Excellent health optimization | | 65-79 | GOOD | Above average, minor improvements possible | | 50-64 | SUBOPTIMAL | Room for improvement | | <50 | NEEDS_ATTENTION | Several areas need focus | ### Axis Scores Each health dimension is scored independently: - **Metabolic**: Blood sugar, insulin, lipids - **Cardiovascular**: Heart health markers - **Inflammatory**: hs-CRP, homocysteine - **Hormonal**: Thyroid, testosterone, cortisol - **Nutritional**: Vitamins, minerals - **Liver/Kidney**: Organ function markers **Important**: It's possible to have a high overall score with one low axis score (or vice versa). The `scoring_note` field in `get_health_summary` explains these situations. ### Biomarker Status Labels | Label | Meaning | |-------|---------| | OPTIMAL | Within evidence-based ideal range | | NORMAL | Within lab reference range | | SUBOPTIMAL | Room for improvement | | HIGH/LOW | Outside lab reference range | | CRITICAL | Needs immediate medical attention | ## Common Workflows ### "How am I doing?" 1. Call `list_available_data` to see what's tracked 2. Call `get_health_summary` for the overall picture 3. Highlight top concerns and recent trends 4. If `scoring_note` is present, explain the score discordance ### "Tell me about my vitamin D" 1. Call `query_biomarker?biomarker=vitamin d` 2. Present history, current status, and trend 3. Note optimal range vs current value ### "What's my CRP?" / "How's my inflammation?" 1. Call `query_biomarker?biomarker=crp` (returns as "CRP" or "hs-CRP" depending on lab) 2. Present the value and trend 3. Explain what CRP measures (inflammation marker) - note if it's high-sensitivity ### "How's my sleep/HRV?" 1. Call `get_wearable_stats?metric=sleep` or `?metric=hrv` 2. Show recent trends and averages 3. Compare to healthy baselines ### "What should I focus on?" 1. Call `get_opportunities?limit=5` 2. Present top opportunities ranked by healthspan impact 3. Explain what each biomarker does and why optimizing it matters ### "How is my LDL trending?" / "When will my CRP get to target?" 1. Call `get_biomarker_trajectory?biomarker=ldl&months=12`. 2. Read off `direction` (improving / worsening / stable) + `slope_per_month`. 3. If `time_to_target_months` is present, surface it ("on this trajectory you'll hit target in ~8 months"). If `supported=false`, explain to the user that they need ≥3 data points and consider the freshness flag. 4. Always call out that the evidence tier is `directional` (linear regression on user history, not a validated population model). ### "How has my biological age trended over time?" / "Show me my bio-age history" 1. Call `get_clock_history?clock=all&months=24`. 2. For each supported clock, surface the per-panel ledger + trend + `delta_years_change`. 3. PhenoAge / Vascular are `validated`; Light BioAge is `validated_emerging` — reflect that asymmetry in language ("PhenoAge says... — Light BioAge, an emerging clock, says..."). 4. NEVER sum across clocks. Each clock evaluates against its own per-panel inputs and uses different mathematical models. ### "How fit am I vs my age peers?" / "How's my stress recovery?" 1. Call `get_health_signal?signal=crf` or `signal=stress_resilience`. 2. Surface the score / category / interpretation. Use `breakdown[]` to explain what's driving the score. 3. ALWAYS qualify with the evidence tier (`directional`) — these are biomarker-derived scores, not validated population-model years. 4. If `primary_concern` is set, surface the recommendation verbatim. ### "What if my LDL dropped to 80?" / "How would my biological age change if X?" 1. Call `compute_what_if` (POST) with the user's hypothetical biomarker target(s). 2. Read off `summary.best_clock` for the headline (one validated clock + delta + direction). 3. Surface PhenoAge / Light BioAge / Vascular as separate rows — they are NOT additive across clocks. Always include the joint caveat from `summary.joint_caveat`. 4. If `model_assumptions` is non-empty (e.g., the LDL → ΔTotal Cholesterol derivation), surface it verbatim — it's load-bearing context for the user. 5. If a clock returns `supported=false` with `status="evidence_gated"`, mention the methylation testing options (TruDiagnostic / Elysium / Clock Foundation). 6. Never say "X years gained" if `direction == "older"`; phrase scenarios that worsen risk as "+ X years older" with a recommendation to consult a clinician. ### "How old am I biologically?" 1. Call `get_biological_age` 2. If available, compare biological vs chronological age 3. Explain what age acceleration means 4. If not available, explain what tests are needed ### "What supplements am I taking?" 1. Call `list_supplements?active_only=true` 2. List active supplements with dosages (use `dose_text` field) 3. Note duration on each supplement ### "What workouts have I done?" 1. Call `get_activities?days=30` 2. Summarize total activity (duration, calories, distance) 3. List recent workouts with key metrics ### "What should I do today?" 1. Call `get_today_actions?timezone=America/New_York` (use user's timezone if known) 2. Group actions by scheduled window (morning, afternoon, evening) 3. Show completion progress 4. Highlight uncompleted actions ### "What should I focus on?" / "What are my health priorities?" 1. Call `get_protocol` 2. Present top priorities with current values and targets 3. Explain why each is prioritized 4. List key recommendations 5. Note protocol phase and days remaining ### "What tests should I do next?" / "Am I due for any blood work?" 1. Call `get_upcoming_tests` 2. Highlight overdue tests first (urgent) 3. List tests due soon with timeframes 4. Mention AI-recommended tests for optimization 5. Note which biomarkers each panel covers ### "Show me my lab reports" / "When was my last blood test?" 1. Call `list_test_results?limit=10` 2. Show reports with dates, lab names, and biomarker counts 3. Note the source (PDF upload, email, manual entry) ### "Give me a full overview of all my biomarkers" 1. Call `list_all_biomarkers` 2. Group by category (metabolic, cardiovascular, etc.) 3. Highlight any critical or high/low values 4. Show status counts (e.g., "12 optimal, 3 suboptimal, 1 high") 5. Note trends (increasing/decreasing/stable) ### "Show me my strength training" / "How's my lifting?" 1. Call `get_strength_training?days=30` 2. Summarize workout frequency and total volume 3. Show muscle group distribution (highlight any imbalances) 4. List recent workouts with top exercises ### "Show me my rowing results" / "How are my erg sessions?" 1. Call `get_erg_results?days=30` 2. Summarize total sessions, distance, and average pace 3. Show per-machine breakdown if using multiple ergs 4. Highlight pace trends (improving/declining) ### "What medications am I on?" / "What prescriptions do I take?" 1. Call `list_medications?active_only=true` 2. List active medications with dosage and frequency 3. Note route and reason if available 4. To see historical medications too, use `active_only=false` ### "What are my medical conditions?" / "Do I have any allergies?" 1. Call `get_medical_profile` 2. Present conditions with status and severity 3. List allergies with severity levels 4. Show family history (relevant for risk assessment) 5. Note active health goals ### "Show me all my health documents" / "What procedure reports do I have?" 1. Call `list_health_documents?limit=20` 2. Show type breakdown (lab reports, procedures, imaging, etc.) 3. List documents with AI summaries 4. Filter by type if user asks about specific category: `document_type=procedure_report` ### "What did my ultrasound show?" / "What are my imaging results?" 1. Call `list_health_documents?document_type=procedure_report` to find imaging documents 2. Call `query_clinical_findings?document_id={id}` with the relevant document ID 3. Group findings by category (measurements, classifications, clinical findings) 4. Highlight key measurements with units and laterality 5. Present grades/classifications prominently 6. Note the report impression if present ### "Do I have a varicocele?" / "Search for specific findings" 1. Call `query_clinical_findings?search=varicocele` (or any search term) 2. Present matching findings with structured values 3. Cross-reference with related findings from the same document ### "What should I read about?" / "Any health articles for me?" 1. Call `get_content_recommendations?limit=5` 2. Present articles with titles and relevance reasons 3. Explain why each is relevant to the user's biomarker profile ## Example API Call ```javascript // Using web_fetch web_fetch({ url: "https://api.gevety.com/api/v1/mcp/tools/get_health_summary", method: "GET", headers: { "Authorization": "Bearer $GEVETY_API_TOKEN", "Content-Type": "application/json" } }) ``` ## Important Guidelines 1. **Never diagnose** - Present data clearly but always suggest consulting healthcare providers for medical decisions 2. **Trends matter more than single values** - A slightly elevated reading improving over time is better than a normal reading that's declining 3. **Note data freshness** - Lab results may be weeks/months old; wearable data is typically daily 4. **Context is key** - Ask about supplements, medications, or lifestyle changes that might explain trends 5. **Privacy first** - Health data is sensitive; don't share or reference specific values outside this conversation ## Error Handling | Error Code | Meaning | Action | |------------|---------|--------| | 401 | Invalid or expired token | User needs to regenerate token at gevety.com/settings | | 404 + `did_you_mean` | Biomarker not found | Suggest alternatives from the response | | 404 | No data found | User may not have uploaded labs yet | | 429 | Rate limited | Wait a moment and retry | ## Getting a Token Users can generate their API token at: **https://gevety.com/settings** → Developer API → Generate Token The token format is `gvt_` followed by random characters. ## Checking for Updates On first use each session, optionally check for updates: ``` GET https://api.gevety.com/api/v1/mcp/tools/status ``` No authentication required. If the request fails or times out, skip the check and proceed normally. Response (when successful): ```json { "clawdbot_skill": { "latest": "1.8.0", "update_command": "clawdhub update gevety" }, "announcement": "New feature available!" } ``` **If `clawdbot_skill.latest` > 1.9.0** (this skill's version), tell the user: > "A Gevety skill update is available. Run: `clawdhub update gevety`" **If `announcement` is present**, mention it once per session. **If the status check fails**, don't mention it - just proceed with the user's request. To manually update: ```bash clawdhub update gevety ```


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)