API Reference

version 1.4.0

Object Schemas

RiderProfile

Field	Type	Default	Description
`weight_kg`	`float`	75	Total weight (rider + gear) for PSI and energy calculations.
`gender`	`string`	male	Gender.
`fitness_level`	`string`	intermediate	Affects difficulty grading. Options: `beginner`, `intermediate`, `advanced`, `pro`.
`sweat_profile`	`string`	default	Genetic sodium loss classification. low: ~400mg/L (Diluted sweat), standard: ~800mg/L (Population average), high: ~1200mg/L (Salty sweater), extreme: ~1800mg/L (Genetic outlier/Heavy loser).

BikeSetup

Field	Type	Default	Description
`bike_type`	`string`	-	Geometry profile (Road, Gravel, MTB, Enduro, E-MTB).
`tire_size`	`string`	29	Diameter (26, 27.5, 29, 32, 700c, 650b).
`tire_width_mm`	`int`	54	Actual width in mm (18 to 75).
`is_ebike`	`bool`	false	Triggers battery consumption logic.
`battery_wh`	`int`	-	Battery capacity in Wh (required if is_ebike is true).

MissionConstraints

Field	Type	Default	Description
`total_length_km`	`int`	-	The total distance of the round trip in kilometers (e.g., 25.0).
`profile`	`string`	cycling-mountain	ORS Routing profile (cycling-mountain, cycling-road, cycling-regular, cycling-electric).
`surface_preference`	`string`	string	Complexity of the loop (higher = more circular).
`complexity`	`int`	3	Triggers battery consumption logic.
`seed`	`int`	42	Randomizer seed to reproduce specific route variations.
`assist_mode`	`string`	Eco	Defines the motor's power output profile (Eco, Trail, Boost). This tactical parameter scales the energy consumption model by adjusting the motor-to-rider assistance ratio, directly impacting predicted battery range and "Safety Buffer" alerts based on terrain resistance.

RouteGeometry

Field	Type	Default	Description
`coordinates`	`list[list[float]]`	`...`	A list of GPS points in GeoJSON format. Each sub-list represents a coordinate triplet: `[longitude, latitude, elevation]`. This sequence is used by the SMA Filter to sanitize elevation and by the Haversine formula for geodesic accuracy.

WeatherSnapshot

Field	Type	Default	Description
`time`	`string`	-	Local time of the forecast snapshot in ISO or HH:MM format.
`temp`	`string`	-	Ambient air temperature (e.g., "15.3°C").
`app_temp`	`string`	-	Apparent (feels-like) temperature considering humidity and wind chill.
`rain_prob`	`string`	-	Probability of precipitation expressed as a percentage (e.g., "15%").
`rain_mm`	`string`	-	Expected rainfall volume measured in millimeters.
`wind`	`string`	-	Average sustained wind speed for the snapshot period.
`gusts`	`string`	-	Maximum predicted wind gust speed.

SafetyAdvice

Field	Type	Default	Description
`status`	`string`	-	Visual alert status indicator (e.g., 🟡 [WATCH], 🔴 [DANGER]).
`message`	`string`	-	Human-readable safety assessment and environmental briefing.
`wind_risk_score`	`float`	-	Numeric risk index (0.0 to 10.0) specifically for crosswinds and stability.
`gear_advice`	`string`	-	Recommended clothing layers and mechanical equipment for the conditions.

MudTactical

Field	Type	Default	Description
`surface_type`	`string`	-	The primary soil or surface type analyzed for saturation (e.g., 'Clay', 'Loam').
`mud_risk_numeric`	`float`	-	Raw TAEL™ moisture index representing the calculated ground water saturation.
`mud_risk_score`	`string`	-	Qualitative risk label derived from the numeric index (e.g., 'Moderate', 'Extreme').
`traction_risk`	`dict[string, string]`	-	Detailed grip assessment including specific tire tread and compound advice.
`trail_damage_risk`	`dict[string, string]`	-	Risk of trail degradation, including probability of rut formation and erosion.
`dry_time_eta`	`string`	-	Estimated time until the trail surface is considered 'ready' or 'optimal' for riding.

MudRiskAnalysis

Field	Type	Default	Description
`status`	`string`	-	The operational status of the soil saturation predictive model.
`metadata`	`object`	-	Technical metadata containing model version, weights, and predictive flags.
`environmental_context`	`object`	-	Environmental data including current soil moisture and 72-hour cumulative rainfall.
`tactical_analysis`	`MudTactical`	-	The granular tactical breakdown of how ground conditions will affect the ride.

MudIntelligence

Field	Type	Default	Description
`score`	`float`	-	TAEL™ mud score (0.0 to 10.0) indicating soil saturation levels.
`label`	`string`	-	Qualitative risk label based on the score (e.g., 'Low', 'High', 'Extreme').
`traction_risk`	`string`	-	Assessment of mechanical tire grip and slip probability on the predicted surface.
`trail_damage_risk`	`string`	-	Risk of creating ruts or damaging trail integrity due to soft ground conditions.
`dry_time_eta`	`string`	-	Estimated time (e.g., '24h', 'Ready Now') until the trail returns to dry/optimal conditions.
`safety_advice`	`string`	-	Tactical advice for riding and bike maintenance in the current soil conditions.

TacticalBriefing

Field	Type	Default	Description
`distance_km`	`float`	-	Total route distance calculated in kilometers.
`elevation_gain_m`	`int`	-	Total positive altitude gain (D+) measured in meters.
`climb_category`	`string`	-	UCI standard or HC climb categorization based on total physical effort.
`avg_gradient`	`string`	-	Average gradient percentage calculated over the entire route distance.
`avg_climb_gradient`	`string`	-	Average gradient considering exclusively the uphill/ascending sectors.
`mud_intelligence`	`MudIntelligence`	-	Ground saturation analytics, soil condition, and TAEL™ index prediction.

MechanicalSetup

Field	Type	Default	Description
`compatible`	`boolean`	-	Flag indicating if the user's bike setup is safely suitable for the route terrain.
`setup_details`	`list[any]`	-	Technical specifics including tire width in mm and localized setup recommendations.
`bike_type`	`string`	-	The specific category of bicycle analyzed (e.g., 'mtb', 'road', 'gravel').

SurfaceEntry

Field	Type	Default	Description
`type`	`string`	-	Normalized surface classification (e.g., 'Paved', 'Grass', 'Unpaved').
`percentage`	`string`	-	The portion of total distance represented by this surface type (e.g., "35.8%").

EmtbMetrics

Field	Type	Default	Description
`estimated_drain_wh`	`float`	-	Predicted total energy consumption for the mission in Watt-hours.
`remaining_battery_pct`	`float`	-	Estimated battery percentage remaining upon reaching the destination.
`safety_buffer_status`	`string`	-	Safety assessment (e.g., 'SAFE', 'CRITICAL') based on remaining capacity.
`usable_wh_at_temp`	`float`	-	Battery capacity (Wh) adjusted for thermal impact on cell efficiency.

EmtbPower

Field	Type	Default	Description
`gravity_resistance`	`float`	-	Power in Watts required to overcome elevation gain based on total system weight.
`rolling_resistance`	`float`	-	Power in Watts required to overcome friction based on surface type and tires.
`aerodynamic_drag`	`float`	-	Power in Watts required to overcome air resistance at predicted speeds.
`rider_contribution`	`int`	-	Estimated average human power output (Watts) provided by the cyclist.
`motor_net_output`	`int`	-	Required average motor assistance (Watts) to maintain the mission pace.

EmtbTactical

Field	Type	Default	Description
`status`	`string`	-	Analysis status indicating if E-MTB simulation was successful.
`battery_metrics`	`EmtbMetrics`	-	Detailed battery drain, safety buffers, and thermal capacity adjustments.
`power_breakdown_w`	`EmtbPower`	-	Physical force breakdown (Watts) including drag, gravity, and friction.
`tactical_advice`	`string`	-	E-MTB specific guidance on mode selection, pacing, and battery management.

RouteSurface

Field	Type	Default	Description
`profile_used`	`string`	-	The specific routing profile applied (e.g., 'cycling-mountain', 'cycling-gravel').
`metadata`	`object`	-	Technical metadata containing timestamps, engine versions, and API flags.
`tactical_briefing`	`TacticalBriefing`	-	Core metrics including distance, elevation gain, and TAEL™ mud intelligence.
`mechanical_setup`	`MechanicalSetup`	-	Technical recommendations for tire pressure and setup compatibility for the terrain.
`surface_breakdown`	`list[SurfaceEntry]`	-	A detailed statistical breakdown of normalized surface types along the route.
`emtb_tactical`	`EmtbTactical`	`null`	Optional battery and power physics metrics for E-MTB profiles.
`safety_warnings`	`list[string]`	-	Critical alerts regarding technical difficulty or environmental hazards.

MissionConditions

Field	Type	Default	Description
`weather`	`list[WeatherSnapshot]`	-	Hourly weather forecast snapshots for the mission duration.
`mud_risk`	`MudRiskAnalysis`	-	Technical analysis of soil saturation and trail rideability.
`max_temp_detected`	`string`	-	The peak temperature identified within the activity window.
`safety_advice`	`SafetyAdvice`	-	Critical safety briefing including gear recommendations and wind risk.

Amenity

Field	Type	Default	Description
`name`	`string`	-	The name of the point of interest (e.g., 'Water Fountain', 'Bike Shop').
`type`	`string`	-	The category of the amenity for tactical filtering.
`distance_m`	`int`	-	The geodesic distance from the route path in meters.
`location`	`dict[string, float]`	-	The exact GPS coordinates (lat/lon) of the amenity.

NutritionBriefing

Field	Type	Default	Description
`fluids`	`object`	-	Total liters and hourly intake rate (ml/h).
`carbohydrates`	`object`	-	Total grams and hourly target (g/h) with absorption ratio.
`electrolytes`	`object`	-	Total and hourly sodium/salt requirements (mg).
`tactical_advice`	`list[string]`	-	Critical nutrition alerts (e.g., Bonk Risk, Heat Stress).

MissionLogistics

Field	Type	Default	Description
`nutrition_plan`	`NutritionPlanWrapper`	-	The physiological fueling plan including fluids, carbs, and electrolytes.
`nearby_amenities`	`list[Amenity]`	-	A list of strategic points detected along or near the route.

EnvironmentalBriefing

Field	Type	Default	Description
`message`	`string`	-	NO GO message.
`rain_avg`	`string`	-	Average probability of precipitation during the mission window.
`wind_max`	`string`	-	Maximum expected wind speed (sustained or gust peak).
`temp_avg`	`string`	-	Average ambient temperature predicted for the activity duration.

PlannerReport

Field	Type	Default	Description
`verdict`	`string`	-	Final tactical decision: GO, WATCH, or NO-GO.
`tactical_color`	`string`	-	Visual risk indicator (e.g., 'GREEN', 'YELLOW', 'RED').
`confidence_score`	`string`	-	AI confidence level (0-100) in the accuracy of the prediction.
`best_window`	`string`	-	The optimal time range identified for the best possible riding conditions.
`environmental_briefing`	`EnvironmentalBriefing`	-	Aggregated summary of primary weather conditions.
`mud_risk_impact`	`string`	-	Predicted soil saturation impact on speed, safety, and trail integrity.

ClimbMetrics

Field	Type	Default	Description
`km_start`	`float`	-	Distance from the start of the track where the climb begins.
`dist_km`	`float`	-	Total length of the specific climbing sector in kilometers.
`gain_m`	`float`	-	Total vertical ascent (D+) of the climb in meters.
`avg_grade`	`float`	-	Average gradient percentage for the entire duration of the sector.
`category`	`string`	-	UCI standard classification (e.g., 'Cat 4', 'Cat 1', 'HC').

PerformanceSim

Field	Type	Default	Description
`climb`	`string`	-	Identifier for the climb including location name and UCI category.
`est_time_min`	`float`	-	Estimated time in minutes to complete the sector at the given intensity.
`est_vam`	`int`	-	Vertical Ascent Meters per hour (VAM) prediction.
`target_wkg`	`float`	-	Required Power-to-Weight ratio (W/kg) for the baseline simulation.
`weather_adjusted_wkg`	`float`	-	W/kg requirement adjusted for wind resistance and air density.

TacticalActionZone

Field	Type	Default	Description
`km`	`float`	-	Exact kilometer mark where the zone or incident starts.
`grade`	`float`	-	Local extreme gradient (steepest ramp) within the zone.
`type`	`string`	-	Classification (e.g., 'Explosive Wall', 'Technical Descent', 'Cobbled Sector').
`difficulty`	`string`	-	Combined technical and physical difficulty assessment.

GeocodingResponse

Field	Type	Default	Description
`payload_version`	`string`	-	The BikeScout protocol version for client-side compatibility.
`status`	`string`	-	Operation status indicator (e.g., 'Success', 'Error').
`lat`	`float`	-	WGS84 Latitude of the identified location.
`lon`	`float`	-	WGS84 Longitude of the identified location.
`display_name`	`string`	-	Full human-readable address or localized place name.
`place_class`	`string`	-	OSM Top-level classification (mapped from `class`).
`place_type`	`string`	-	Specific location sub-type (mapped from `type`).
`importance`	`float`	-	Search relevance score (0.0 to 1.0) based on location popularity.

TacticalForecastResponse

Field	Type	Default	Description
`payload_version`	`string`	-	The BikeScout protocol version for client-side compatibility.
`status`	`string`	-	Current status of the weather service provider and data availability.
`metadata`	`object`	-	Contextual location data, elevation of source, and timezone metadata.
`tactical_forecast`	`list[WeatherSnapshot]`	-	Hourly weather breakdown specifically windowed for the mission or race duration.
`reference_conditions`	`object`	-	Aggregated weather metrics used as baselines for performance and physiological adjustments.
`safety_advice`	`SafetyAdvice`	-	Strategic safety briefing covering risks like crosswinds, thermal strain, or lightning.

RouteSurfaceResponse

Field	Type	Default	Description
`payload_version`	`string`	-	The BikeScout protocol version for client-side compatibility.
`status`	`string`	-	Overall operation status indicator (e.g., 'Success', 'Error').
`profile_used`	`string`	-	The specific routing profile applied to the analysis (e.g., 'cycling-mountain').
`metadata`	`object`	-	Technical metadata including timestamps, API flags, and processing logs.
`tactical_briefing`	`TacticalBriefing`	-	Core mission metrics including distance, elevation gain, and mud/soil intelligence.
`mechanical_setup`	`MechanicalSetup`	-	Specific recommendations for tire pressure, casing, and setup compatibility.
`surface_breakdown`	`list[SurfaceEntry]`	-	Aggregated and normalized statistics of all terrain types encountered.
`emtb_tactical`	`EmtbTactical`	`null`	Optional power and battery metrics; only populated if `is_ebike` is true.
`safety_warnings`	`list[string]`	-	List of critical alerts regarding hazardous segments, technical risks, or weather impact.

FullMissionBriefingResponse

Field	Type	Default	Description
`payload_version`	`string`	-	BikeScout protocol version.
`status`	`string`	-	Operation status (Success/Error).
`info`	`RouteInfo`	-	Structured data regarding the route's morphology and difficulty.
`conditions`	`MissionConditions`	-	Environmental analysis synchronized with the mission time window.
`logistics`	`MissionLogistics`	-	Tactical recommendations for mechanical setup, nutrition, and timing.
`map_path`	`string`	-	The local file path for the static map image of the route.
`mcp_resource_uri_map`	`string`	-	The MCP URI for direct map layer access.
`gpx_export_path`	`string`	-	The local file path of the generated GPX file.
`mcp_resource_uri_gpx`	`string`	-	The MCP URI for downloading the GPX mission file.
`elevation_profile_path`	`string`	-	The local file path for the elevation profile chart.
`mcp_resource_uri_elevation_profile`	`string`	-	The MCP URI for the visual altimetry analysis.
`gpx_stats`	`dict[string, int]`	-	Dictionary of raw metadata extracted from the GPX file.

HydrationScoutResponse

Field	Type	Default	Description
`payload_version`	`string`	-	BikeScout protocol version.
`status`	`string`	-	Operation status (Success/Error).
`weather_context`	`WeatherContext`	-	Environmental factors that influenced the hydration/sodium calculation.
`mission_nutrition_briefing`	`NutritionBriefing`	-	Detailed fluid, carb, and electrolyte plan.

StrategicPlannerResponse

Field	Type	Default	Description
`payload_version`	`string`	-	The BikeScout protocol version for client-side compatibility.
`status`	`string`	-	Operation status indicator (e.g., 'Success', 'Error').
`metadata`	`object`	-	Contextual metadata including analyzed date, surface type, and location.
`planner_report`	`PlannerReport`	-	The final strategic assessment and tactical timing recommendations.

GpxRaceAuditResponse

Field	Type	Default	Description
`payload_version`	`string`	-	The BikeScout Protocol version for client-side compatibility.
`status`	`string`	-	Overall success/error indicator of the race analysis engine.
`mode`	`string`	-	Selected activity mode for physics engine logic ('ROAD' or 'MTB').
`target_date`	`string`	-	Date used for synchronizing weather, wind, and mud impact models.
`track_metrics`	`dict`	-	Dictionary of core track data: distance, total ascent, and peak altitude.
`planning_tools`	`object`	-	Container for weather snapshots, nutrition strategy, and mud risk analysis.
`climb_analysis`	`list[ClimbMetrics]`	-	List of all detected climbing sectors with UCI categorization.
`performance_simulation`	`list[PerformanceSim]`	-	Climb-by-climb power, VAM, and timing estimates.
`tactical_alerts`	`list[dict]`	-	Specific alerts for race dynamics (e.g., 'ECHELON RISK', 'HEADWIND SECTOR').
`pre_climb_positioning`	`list[dict]`	-	Strategic points where the rider should optimize pack position.
`tactical_action_zones`	`list[TacticalActionZone]`	-	Key points designated for potential attacks or extreme technical caution.
`report_path`	`string`	`null`	File path to the generated high-fidelity PDF race book/roadbook.

TOOL

geocode_location

Description

Primary resolution engine for geographical names. Finds latitude and longitude for any natural language place name (cities, mountain passes, specific addresses, or points of interest). Crucial Step: Use this tool to resolve coordinates before calling any routing or weather tools if you only have a location name.

Parameters

Parameter	Type	Status	Description
`location_name`	`string`	Required	The natural language name of the place (e.g., "Passo dello Stelvio", "Courmayeur").
`language`	`string`	Default: "en"	Language for localized results (e.g., 'it', 'fr', 'es'). Maps to Accept-Language header.

Returns

GeocodingResponse

● lat/lon: Precise floating-point coordinates for routing engines.
● display_name: The full, formal localized name of the resolved location.
● importance: A reliability score (0.0 to 1.0) to evaluate the match quality.
● place_class/type: Contextual tags (e.g., 'city', 'mountain', 'peak') used to distinguish between different types of landmarks.

TOOL

trail_scout

Description

Advanced trail discovery engine. Returns comprehensive route data, technical difficulty assessment, navigation files (GPX), and visual altimetry reports. Supports both Round Trips (single point) and A to B routing. Synchronizes with weather and soil models to provide real-time tactical advice. If target_date is omitted, it defaults to the current day.

Parameters

Parameter	Type	Status	Description
`latitude`	`float`	Required	Starting point latitude (WGS84).
`longitude`	`float`	Required	Starting point longitude (WGS84).
`rider`	`RiderProfile`	Required	Rider's physiological profile (weight, FTP, etc.).
`bike`	`BikeSetup`	Required	Bike technical setup (weight, tires, e-bike specs).
`mission`	`MissionConstraints`	Required	Activity constraints (start time, intensity).
`dest_latitude`	`float`	Optional	Destination latitude for A-B routing.
`dest_longitude`	`float`	Optional	Destination longitude for A-B routing.
`style`	`enum`	"filled"	Chart style: `sparkline`, `filled`, `bars`.
`target_date`	`string`	Optional	Custom date (YYYY-MM-DD) for predictive analysis.
`include_gpx`	`bool`	Default: true	Generate and export a navigation GPX file.
`include_map`	`bool`	Default: false	Generate a static PNG map of the route.
`include_poi`	`bool`	Default: false	Generate amenities and points of interest.
`include_altimetry`	`bool`	Default: false	Generate the altimetry profile of the route.
`include_weather`	`bool`	Default: false	Generate weather conditions report.
`include_mud_analysis`	`bool`	Default: false	Generate a report including mud analysis.
`include_nutrition_plan`	`bool`	Default: false	Generate a nutrition plan report.

Returns

FullMissionBriefingResponse

● info: Route morphology, surface analysis (TAEL™ mud risk), and mechanical/PSI guides.
● conditions: Hourly synchronized weather, rain probability, and safety gear briefings.
● logistics: Hydration/Nutrition plan and strategic amenities (water fountains, etc.) detected along the path.
● Visual Assets: Native URIs for Map, Elevation Profile, and GPX navigation file for direct chat rendering.
● gpx_stats: Technical summary of trace integrity (point count, segment healing).

TOOL

check_trail_weather

Description

Advanced cycling-specific weather assistant designed for both real-time decisions and long-term event planning. It provides hyper-localized analysis of temperature, precipitation risk, and wind dynamics. Smart Window: If target_date is provided, it analyzes the full event window (ideal for races); otherwise, it focuses on the immediate 4-hour tactical window.

Parameters

Parameter	Type	Status	Description
`lat`	`float`	Required	Latitude of the specific trail or event sector.
`lon`	`float`	Required	Longitude of the specific trail or event sector.
`target_date`	`string`	Optional	The date of the event (YYYY-MM-DD). Defaults to the current tactical window.

Returns

TacticalForecastResponse

● status: Confirmation of the API operation and data freshness.
● metadata: Contextual data including timezone synchronization and resolved location coordinates.
● tactical_forecast: A granular hourly breakdown of temperature, rain probability (%), and wind speed/direction.
● reference_conditions: Aggregated key metrics (Min/Max/Avg) for the selected analysis window.
● safety_advice: Mission-critical briefing covering wind risk scores, thermal stress alerts, and suggested gear/clothing.

TOOL

ride_window_planner

Description

Tactical Go/No-Go Decision Engine. This tool identifies the optimal time range for an activity by cross-referencing weather stability with the TAEL™ soil drainage efficiency. It calculates the "drying lag" based on the specific surface type to ensure the mission doesn't coincide with peak mud risk or dangerous environmental shifts.

Parameters

Parameter	Type	Status	Description
`lat`	`float`	Required	Latitude of the mission area.
`lon`	`float`	Required	Longitude of the mission area.
`ride_duration_hours`	`float`	Default: 2.0	Planned duration of the cycling session in decimal hours.
`surface_type`	`enum`	"dirt"	Surface type: `dirt`, `gravel`, `asphalt`, `sand`, `clay`.
`target_date`	`string`	Optional	The date of the event (YYYY-MM-DD). Defaults to today's schedule.

Returns

StrategicPlannerResponse

● metadata: Contextual info including the local solar window (sunrise/sunset) to avoid riding in the dark.
● planner_report: The final GO/WATCH/NO-GO verdict with a visual risk color (Green/Yellow/Red).
● environmental_briefing: Aggregated summary of rain probability, max wind gusts, and average temperature.
● best_window: The specific time range (e.g., 09:00 - 11:00) identified as safest and driest.
● mud_risk_impact: A percentage indicating how soil saturation levels might affect traction and overall mission success.

TOOL

hydration_scout

Description

Physiological Intelligence Engine. This tool generates a mission-specific fueling strategy by cross-referencing localized weather dynamics (heat index, humidity, and solar radiation) with the predicted intensity of the effort. It calculates sweat rates and glycogen depletion to provide precise targets for fluids, carbohydrates, and sodium.

Parameters

Parameter	Type	Status	Description
`lat`	`float`	Required	Latitude of the mission area.
`lon`	`float`	Required	Longitude of the mission area.
`duration_hours`	`float`	Default: 2.0	Estimated time in the saddle (decimal hours).
`intensity_score`	`int`	Default: 3	Perceived effort (1: Recovery, 3: Tempo, 5: Race/Max effort).
`weight`	`float`	Default: 70	Weight in KG.
`gender`	`string`	Default: male	"male" or "female". Scales sweat rate based on plasma volume variances.
`sweat_profile`	`string`	Default: default	Genetic sodium loss classification. - "low": ~400mg/L (Diluted sweat). - "standard": ~800mg/L (Population average). - "high": ~1200mg/L (Salty sweater). - "extreme": ~1800mg/L (Genetic outlier/Heavy loser).

Returns

HydrationScoutResponse

● weather_context: Environmental factors (Temp, Humidity, Wind) that influenced the physiological stress calculation.
● fluids: Total volume required and hourly intake rate (ml/h) to maintain hydration.
● carbohydrates: Total grams and hourly target (g/h) based on intensity and duration.
● electrolytes: Sodium and salt requirements (mg) to prevent cramping and hyponatremia.
● tactical_advice: Critical alerts regarding heat stress, bonk risk, or specific absorption strategies.

TOOL

analyze_gpx_track

Description

High-Fidelity Professional Race Audit. This is the most advanced analysis engine, designed to transform a raw GPX file into a complete tactical roadbook. It simulates professional racing dynamics, calculating UCI climb categories, VAM (Vertical Ascent Meters), and specific W/kg requirements adjusted for environmental friction (wind and air density). It also identifies strategic risks such as echelon (crosswind) zones and optimal attack points.

Parameters

Parameter	Type	Status	Description
`gpx_url`	`string`	Required	Remote URL or local path of the GPX file.
`rider_weight_kg`	`float`	Default: 75	Body mass for Power-to-Weight (W/kg) calculations.
`rider_gender`	`string`	Default: male	Gender.
`rider_fitness_level`	`string`	Default: intermediate	User's athletic preparation level. Affects fatigue and climbing logic. Default "intermediate"
`sweat_profile`	`string`	Default: standard	Genetic sodium loss classification. - "low": ~400mg/L (Diluted sweat). - "standard": ~800mg/L (Population average). - "high": ~1200mg/L (Salty sweater). - "extreme": ~1800mg/L (Genetic outlier/Heavy loser).
`bike_weight_kg`	`float`	Default: 8.5	Mass of the bike.
`pro_intensity`	`float`	Default: 1.3	Effort multiplier (1.0: Amateur, 1.6: Pro, 2.0: Attack).
`activity_type`	`enum`	"road"	`road` or `mtb`.
`target_date`	`string`	Optional	Race date (YYYY-MM-DD) for weather/mud prediction.
`start_hour / end_hour`	`int`	Optional	Race window (0-23) for time-averaged metrics.
`report`	`bool`	Default: false	Generate a professional PDF race book.

Returns

GpxRaceAuditResponse

● track_metrics: Core telemetry (distance, total ascent, peak altitude).
● climb_analysis: Granular breakdown of every climb with UCI categorization.
● performance_simulation: Predicted sector times, VAM, and weather-adjusted W/kg targets.
● tactical_alerts: Critical warnings for echelons (crosswinds), technical action zones, and positioning cues.
● planning_tools: Integrated nutrition plan and environmental risk summaries.
● report_path: URI to the generated professional PDF roadbook (if report=True).

SKILL

Name	Description
🇺🇸 Moab, Utah	High-desert survival, Slickrock traction, extreme hydration dynamics.
🇮🇹 Dolomites, Italy	High-altitude weather vigilance, UNESCO limestone grip & vertical gain.
🇫🇷 Arenberg Forest	Vibration damping on Pavé, stone humidity risk & TAEL™ soil lag.
🇮🇹 Finale Ligure	EWS standards, brake fade management, maritime limestone tuning.
🇮🇹 Castelli Romani	Volcanic soil drainage (clay/sand), technical volcanic rock descents.
🇦🇺 Derby, Tasmania	Granite slab traction, temperate rainforest mud-risk, flow-state mechanics.
🇯🇵 Shimanami Kaido	Salt-air corrosion notes, bridge crosswind analysis, multi-island logistics.
🔧 Mechanical and Tires setup	Pressure optimization, tubeless sealant verification, and drivetrain lubrication for high-stress terrains.
🛡️ Safety Guide	M-Check protocols, helmet integrity verification, and specialized safety checks by bike discipline.