RunReady

Tools (5)

Extracted live via the executor SDK.

• get_interactive_course_map

  Displays an interactive course map widget for a running event. Use this tool when the user wants to SEE or VISUALIZE the course — requests like 'show me the course', 'display the map', 'let me see the route', or 'visualize the elevation'. Returns minimal event identity (name, unit system, GPX URL) plus an interactive map widget with GPX track, elevation profile, and distance markers. For detailed course analysis data (stats, sections, challenges) to answer questions, use get_course_route_insights_for_qa instead.

  When ok is false: Do NOT describe course details, map features, or elevation data as if the tool succeeded. Always quote the error message to explain the failure. If error_code is EVENT_NOT_SUPPORTED, the requested event is not yet supported by RunReady — tell the user RunReady doesn't have this race yet (not that it doesn't exist), list suggested_events as alternatives if present, and mention get_supported_events for the full list. If error_code is absent, it is an operational or configuration error — relay the error message without claiming the race is unsupported. You may share general knowledge only if explicitly labeled as such and not presented as an official RunReady guide.

• get_course_route_insights_for_qa

  Retrieves detailed course analysis data for answering questions about a running event. Use this tool when the user asks QUESTIONS about the course — requests like 'what are the hardest parts?', 'where are the aid stations?', 'how much elevation gain?', 'tell me about the course', or 'what should I know about this race?'. Returns structured data including event identity, key stats, elevation/grade summaries, segment-by-segment breakdown (challenges, climbs/descents), and aid stations. Does NOT return a map widget — for visual map display, use get_interactive_course_map instead.

  When ok is false: Do NOT describe course stats, sections, or elevation data as if the tool succeeded. Always quote the error message to explain the failure. If error_code is EVENT_NOT_SUPPORTED, the requested event is not yet supported by RunReady — tell the user RunReady doesn't have this race yet (not that it doesn't exist), list suggested_events as alternatives if present, and mention get_supported_events for the full list. If error_code is absent, it is an operational or configuration error — relay the error message without claiming the race is unsupported. You may share general knowledge only if explicitly labeled as such and not presented as official RunReady analysis.

• get_personalized_pacing_plan

  Calculates a pacing plan for a specific running event using detailed course data (distance, elevation profile, and on-course stations). Returns segment splits, cumulative times, and optional checkpoint tables based on a selected pacing strategy (Even Pace, Even Effort, Negative Split, etc.) and an estimated time lost per aid station. When all optional parameters are provided (goal_time, estimated_start_time, pacing_strategy_id, aid_station_seconds), the tool automatically calculates and returns the pacing plan. If any parameters are missing, an interactive widget prompts the user for the remaining inputs. Note: All 'pace' values in the output are elapsed pace (including aid station time), not moving pace.

  Integration with weather tool: The output of this tool can be passed directly as the pacing_plan parameter to analyze_historic_course_weather to enable personalized weather timing. If a pacing plan has been generated for the same event in this conversation, always include it when calling the weather tool — personalized weather is preferred over default mode. Do not reuse a pacing plan from a different event. For best results, pass the complete data object without modification — include the full splits array, all assumptions, and the unit_system. Do not trim or sample the splits.

  When ok is false: Do NOT present pacing data or split tables as if the tool succeeded. Always quote the error message to explain the failure. If error_code is EVENT_NOT_SUPPORTED, the requested event is not yet supported by RunReady — tell the user RunReady doesn't have this race yet (not that it doesn't exist), list suggested_events as alternatives if present, and mention get_supported_events for the full list. If error_code is absent, it is an operational error — relay the error message without claiming the race is unsupported.

• analyze_historic_course_weather

  Retrieves historic weather data for a running event's course and returns a compact plot payload for visualization. Returns temperature ranges (5-year min/max band, average, and previous year actuals), plus sanitized data for precipitation, humidity, and wind. Use this when the user asks about expected weather conditions, temperature forecasts, or what to expect on race day based on historical patterns.

  Personalized mode: If a pacing plan has already been generated for the same event in this conversation, ALWAYS include it as the pacing_plan parameter — personalized weather is strictly better than default mode and users expect it. To generate one, FIRST call get_personalized_pacing_plan to get splits, THEN pass its complete data object as the pacing_plan parameter to this tool WITHOUT trimming or sampling the splits array. The most robust approach is to pass the pacing plan output as-is (unit_system + assumptions + full splits). Personalized mode shows weather at projected arrival times rather than linear distance-to-time mapping.

  Key requirements for personalization to succeed:

  1. Pass the COMPLETE splits array from the pacing plan (every segment, not a subset).
  2. Include assumptions.start_time (critical field).
  3. Use the same unit_system in the pacing_plan as was used when calling get_personalized_pacing_plan. The pacing_plan unit_system must match the resolved weather data unit system for personalization to activate (the API may rarely fall back to the opposite system if data is unavailable).
  4. Use consistent HH:MM:SS 24-hour zero-padded format for all clock times.

  Fallback behavior: If pacing_plan is missing, invalid, or cannot be parsed, the tool automatically falls back to default mode (linear mapping from start to cutoff). The tool never fails due to a malformed pacing plan.

  Input: event name + optional unit system + optional pacing_plan. Output: event identity, schedule context, mode flags, compact plot payload, sanitized weather data, and summary.

  When ok is false: Do NOT present weather data or forecasts as if the tool succeeded. Always quote the error message to explain the failure. If error_code is EVENT_NOT_SUPPORTED, the requested event is not yet supported by RunReady — tell the user RunReady doesn't have this race yet (not that it doesn't exist), list suggested_events as alternatives if present, and mention get_supported_events for the full list. If error_code is absent, it is an operational error (e.g., weather data not yet generated) — relay the error message without claiming the race is unsupported.

• get_supported_events

  Returns a list of all running events currently supported by RunReady. Use this tool when you need to (a) confirm whether a specific race or event is supported, (b) disambiguate similar race names, or (c) provide users with canonical links to RunReady course guides. An event is considered "supported" if it is active and has at least one published course guide. Returns event name, date, type, available unit systems, and canonical URLs for each guide.