gevety

What this skill does

# 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

### 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`: Wh