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:

• Get a Gevety account: Sign up at https://gevety.com if they don't have one
• Upload blood tests: They need to upload lab reports to have biomarker data
• Generate an API token:
• Go to https://gevety.com/settings
• Click "Developer API" tab
• Click "Generate Token"
• Copy the token (starts with gvt_)
• Configure Clawdbot: Add the token to ~/.clawdbot/clawdbot.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:

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")

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

• 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

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.)

• 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.)

• 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

• 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

• supplements: List of supplements with dosage, frequency, duration
• active_count: Number of currently active supplements
• total_count: Total supplements tracked

• 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

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.)

• 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

• 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, etc.)

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

• 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

• 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

• 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

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

• 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)

• reports: List of lab reports
• total_reports: Total number of reports

• 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)

• 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)

• 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

• recommendations: List of recommended articles
• total_available: Total recommendations available

• 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

Interpreting Scores

Healthspan Score (0-100)

Axis Scores

• 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

Biomarker Status Labels

Common Workflows

"How am I doing?"

• Call list_available_data to see what's tracked
• Call get_health_summary for the overall picture
• Highlight top concerns and recent trends
• If scoring_note is present, explain the score discordance

"Tell me about my vitamin D"

• Call query_biomarker?biomarker=vitamin d
• Present history, current status, and trend
• Note optimal range vs current value

"What's my CRP?" / "How's my inflammation?"

• Call query_biomarker?biomarker=crp (returns as "CRP" or "hs-CRP" depending on lab)
• Present the value and trend
• Explain what CRP measures (inflammation marker) - note if it's high-sensitivity

"How's my sleep/HRV?"

• Call get_wearable_stats?metric=sleep or ?metric=hrv
• Show recent trends and averages
• Compare to healthy baselines

"What should I focus on?"

• Call get_opportunities?limit=5
• Present top opportunities ranked by healthspan impact
• Explain what each biomarker does and why optimizing it matters

"How old am I biologically?"

• Call get_biological_age
• If available, compare biological vs chronological age
• Explain what age acceleration means
• If not available, explain what tests are needed

"What supplements am I taking?"

• Call list_supplements?active_only=true
• List active supplements with dosages (use dose_text field)
• Note duration on each supplement

"What workouts have I done?"

• Call get_activities?days=30
• Summarize total activity (duration, calories, distance)
• List recent workouts with key metrics

"What should I do today?"

• Call get_today_actions?timezone=America/New_York (use user's timezone if known)
• Group actions by scheduled window (morning, afternoon, evening)
• Show completion progress
• Highlight uncompleted actions

"What should I focus on?" / "What are my health priorities?"

• Call get_protocol
• Present top priorities with current values and targets
• Explain why each is prioritized
• List key recommendations
• Note protocol phase and days remaining

"What tests should I do next?" / "Am I due for any blood work?"

• Call get_upcoming_tests
• Highlight overdue tests first (urgent)
• List tests due soon with timeframes
• Mention AI-recommended tests for optimization
• Note which biomarkers each panel covers

"Show me my lab reports" / "When was my last blood test?"

• Call list_test_results?limit=10
• Show reports with dates, lab names, and biomarker counts
• Note the source (PDF upload, email, manual entry)

"Give me a full overview of all my biomarkers"

• Call list_all_biomarkers
• Group by category (metabolic, cardiovascular, etc.)
• Highlight any critical or high/low values
• Show status counts (e.g., "12 optimal, 3 suboptimal, 1 high")
• Note trends (increasing/decreasing/stable)

"What should I read about?" / "Any health articles for me?"

• Call get_content_recommendations?limit=5
• Present articles with titles and relevance reasons
• Explain why each is relevant to the user's biomarker profile

Example API Call

// 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

• Never diagnose - Present data clearly but always suggest consulting healthcare providers for medical decisions
• Trends matter more than single values - A slightly elevated reading improving over time is better than a normal reading that's declining
• Note data freshness - Lab results may be weeks/months old; wearable data is typically daily
• Context is key - Ask about supplements, medications, or lifestyle changes that might explain trends
• Privacy first - Health data is sensitive; don't share or reference specific values outside this conversation

Error Handling

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):

{
  "clawdbot_skill": { "latest": "1.6.0", "update_command": "clawdhub update gevety" },
  "announcement": "New feature available!"
}

If clawdbot_skill.latest > 1.6.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:

clawdhub update gevety