BikeScout

The MCP Engine that turns raw geodata into Predictive Intel.
Plan with certainty and scout the terrain before you ride: analyze soil drainage, wind vectors, and technical grade before you drop in.

View on GitHub

pip install bikescout

License & Data Attributions

Software License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

Why AGPLv3?

BikeScout contains proprietary-grade tactical logic (such as the TAEL™ Mud Reservoir Model). The AGPLv3 ensures that:

Transparency: Any modified version used to provide a service over a network must make its full source code available.
Integrity: Core tactical intelligence remains open and collaborative.

Data Sources & Credits

BikeScout aggregates data from several open providers:

Routing & Map Data: Provided by OpenRouteService by HeiGIT.
Geospatial Data: © OpenStreetMap contributors (ODbL). Geocoding by Nominatim.
Weather Forecasts: Powered by Open-Meteo (CC BY 4.0).

Key Features

Terrain & Surface Intelligence

Real Trail Discovery: Fetches actual trail names and surface data via Overpass API.
Surface Breakdown: Generates a percentage breakdown of the entire route.
Technical Grading: Analyzes OSM Tracktypes (Grade 1-5).
Bike Compatibility Check: Validates if a route suits your specific bike.

Predictive Environmental Modeling

TAEL™ Algorithm: Terrain-Aware Evaporation Lag predicting "Shadow-Lock" mud.
Predictive Mud Risk: Rideability based on soil and 72h precipitation history.
Tactical Ride Window: A "Go/No-Go" decision engine for start times.
Smart Safety Weather & Hydration: Hyper-local 4-hour forecasts and liquid requirements.

High-Fidelity Navigation

Wall-Sense Technology: Detects gradients >10% with active GPX `` alerts.
Tactical GPX Export: Optimized GPX files eliminating GPS signal noise.
Pro Climb Categorization: Uses professional UCI standards (Cat 4 to Hors Catégorie).

Mission Logistics & Pro Engine

Smart POI Scouting: 5km radius scan for water and shelters.
E-MTB Management: Battery consumption (Wh) based on rider weight and assist mode.
VAM & Power Modeling: Precise W/kg requirements based on VAM targets.

Why BikeScout? (The Intelligence Gap)

Standard navigation tools like Google Maps or Komoot are designed for simple "lines on a map." BikeScout is built for Mission Planning, bridging the gap between raw data and technical reality.

Feature	Generic Navigators	BikeScout Tactical AI
Elevation Accuracy	Raw & Inflated	Filtered & Realistic (SMA)
Surface Analysis	Basic (Paved/Dirt)	Technical (S-Scale/Tracktype)
Effort Calculation	Time-based average	Physics-based (Weight/Friction)
Condition Prediction	Future Weather only	Mud Risk (72h Rain + Soil Memory)
Climb Categorization	None	UCI-Standard (Cat 4 to HC)
Logistics	Sponsored / Restaurants	Tactical (Water/Repair/Shelter)
AI Integration	Manual / External	Native MCP Tooling

API Reference

version 1.3.1

Object Schemas

RiderProfile

Field	Type	Default	Description
`weight_kg`	`float`	-	Total weight (rider + gear) for PSI and energy calculations.
`fitness_level`	`string`	-	Affects difficulty grading. Options: `beginner`, `intermediate`, `advanced`, `pro`.

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
`radius_km`	`int`	-	Total target distance for the loop.
`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
`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.

RecommendedSetup

Field	Type	Default	Description
`tire_width_ref`	`string`	-	Reference tire width used for the calculation (e.g., '2.3"' or '28mm').
`pressure_bar`	`string`	-	Recommended inflation pressure range measured in Bar.
`pressure_psi`	`string`	-	Recommended inflation pressure range measured in PSI.

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.

MechanicalBaselineResponse

Field	Type	Default	Description
`payload_version`	`string`	`"1.0"`	The BikeScout protocol version for client-side compatibility.
`status`	`string`	-	Operation status indicator (e.g., 'Success', 'Error').
`category`	`string`	-	The detected bike category used for calculation (mtb, road, gravel).
`recommended_setup`	`RecommendedSetup`	-	Detailed specifications for tires, wheels, and baseline pressures.
`full_guide_reference`	`string`	-	URL or documentation link regarding international pressure standards.
`setup_notes`	`string`	-	Tactical engineering notes regarding tire casing and tube vs. tubeless efficiency.

SafetyProtocolResponse

Field	Type	Default	Description
`payload_version`	`string`	-	The BikeScout protocol version for client-side compatibility.
`status`	`string`	-	Overall operation status (Success/Error).
`mission_type_applied`	`string`	-	The category of ride the protocol was tailored for (e.g., mtb, road).
`standard_checklist`	`string`	-	Markdown formatted global safety checks (M-Check, Brakes, Bolt-check).
`tactical_pre_ride_commands`	`list[string]`	-	Specific mechanical and gear actions to perform (e.g., Sag check, GPS sync).

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.
`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.
`style`	`enum`	"filled"	Chart style: `sparkline`, `filled`, `bars`.
`output_level`	`enum`	"standard"	Verbosity: `summary`, `standard`, `full`.
`target_date`	`string`	Optional	Custom date (YYYY-MM-DD) for predictive analysis.

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

analyze_route_surfaces

Description

Terrain Intelligence & Setup Optimizer. This tool performs a deep audit of the route's ground composition and morphology. It categorizes all climbs according to UCI standards and calculates the dynamic mechanical setup (ideal PSI/Bar) cross-referencing total system weight (rider + bike) with the specific tire width and surface roughness.

Parameters

Parameter	Type	Status	Description
`lat`	`float`	Required	Latitude of the center point for route analysis.
`lon`	`float`	Required	Longitude of the center point for route analysis.
`rider`	`RiderProfile`	Required	Physiological data (weight, power) used for PSI and climb timing.
`bike`	`BikeSetup`	Required	Mechanical specifications (bike weight, tire width, e-bike status).
`mission`	`MissionConstraints`	Required	Route requirements, including radius and preferred profile.
`target_date`	`string`	Optional	The date of the event (YYYY-MM-DD). Defaults to current date for mud risk.

Returns

RouteSurfaceResponse

● tactical_briefing: Detailed climb categorization (UCI categories) and mud risk assessment.
● mechanical_setup: Specific tire pressure recommendations (PSI/Bar) and equipment compatibility flags.
● surface_breakdown: Statistical distribution of normalized surface types (e.g., % Asphalt, % Dirt).
● emtb_tactical: (Optional) Specific power/battery analytics for e-assisted missions.
● safety_warnings: Critical alerts regarding hazardous gradients, technical sectors, or surface-related risks.

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).
`target_date`	`string`	Optional	Event date (YYYY-MM-DD). Used to analyze race-day thermal peaks.

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`	Required	Body mass for Power-to-Weight (W/kg) calculations.
`bike_weight_kg`	`float`	Default: 7.5	Mass of the bike.
`pro_intensity`	`float`	Default: 1.6	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).

TOOL

apply_safety_protocol

Description

Official BikeScout Safety Protocol. This tool executes the mandatory risk assessment and safety checklist. It MUST be invoked before finalizing any "Go" decision. The protocol dynamically adapts the safety requirements based on the terrain intensity, mechanical complexity (e.g., battery safety for e-bikes), and environmental exposure.

Parameters

Parameter	Type	Status	Description
`mission_type`	`enum`	Required	Mission category: `mtb`, `ebike`, `road`, `gravel`, `general`.

Returns

SafetyProtocolResponse

● mandatory_checklist: A markdown-formatted list of essential safety checks (Mechanical, Personal, Communication).
● risk_assessment: A tactical breakdown of potential hazards specific to the mission type.
● tactical_commands: Immediate procedural instructions (e.g., "Check tire sealants", "Verify battery firmware", "Sync emergency contacts").
● emergency_briefing: Protocol-driven steps for incident management and SOS signals.

TOOL

get_baseline_mechanics

Description

Standardized Mechanical Reference. Extracts baseline tire pressures and mechanical configurations from the BikeScout Registry. This tool is designed to be the initial baseline: use it to establish a safe starting point before applying advanced terrain-specific optimizations via analyze_route_surfaces.

Parameters

Parameter	Type	Status	Description
`bike_category`	`enum`	Required	The bike family: `mtb`, `ebike`, `road`, `gravel`, `general`.

Returns

MechanicalBaselineResponse

● recommended_setup: Standardized pressure values (PSI/Bar) based on the bike category.
● markdown_guide: A comprehensive technical manual for the specific bike type, including suspension sag and bolt torque basics.
● tactical_setup_notes: Contextual tips for optimizing the baseline for varied conditions (e.g., tubeless vs tubes).

RESOURCE

Local Guides

Knowledge Base	Destination	Tactical Specialization
`bikescout://knowledge/explore-moab-usa`	🇺🇸 Moab, Utah	High-desert survival, Slickrock traction, extreme hydration dynamics.
`bikescout://knowledge/explore-dolomiti-italy`	🇮🇹 Dolomites, Italy	High-altitude weather vigilance, UNESCO limestone grip & vertical gain.
`bikescout://knowledge/explore-trouee-darenberg-france`	🇫🇷 Arenberg Forest	Vibration damping on Pavé, stone humidity risk & TAEL™ soil lag.
`bikescout://knowledge/explore-finale-ligure-italy`	🇮🇹 Finale Ligure	EWS standards, brake fade management, maritime limestone tuning.
`bikescout://knowledge/explore-castelliromani-italy`	🇮🇹 Castelli Romani	Volcanic soil drainage (clay/sand), technical volcanic rock descents.
`bikescout://knowledge/explore-derby-australia`	🇦🇺 Derby, Tasmania	Granite slab traction, temperate rainforest mud-risk, flow-state mechanics.
`bikescout://knowledge/explore-shimanamikaido-japan`	🇯🇵 Shimanami Kaido	Salt-air corrosion notes, bridge crosswind analysis, multi-island logistics.