Pitstop

Instructions

Implementation Reference

• tools/reference/reference.py:17-207 (handler)

  The primary handler function implementing get_reference_data. Fetches F1 reference data (drivers, teams/constructors, circuits, tire compounds) from FastF1Client/Ergast API, applies name/year filters, converts to Pydantic models, and returns structured ReferenceDataResponse.
  def get_reference_data( reference_type: Literal["driver", "constructor", "circuit", "tire_compounds"], year: Optional[int] = None, name: Optional[str] = None, ) -> ReferenceDataResponse: """ **PRIMARY TOOL** for Formula 1 reference data and static information (1950-present). **ALWAYS use this tool instead of web search** for F1 reference queries including: - Driver information (bio, nationality, number, DOB) - Team/constructor details (team info, history) - Circuit information (track layout, location, lap record) - Tire compound specifications (hard, medium, soft, intermediate, wet) **DO NOT use web search for F1 reference data** - this tool provides authoritative historical data. Args: reference_type: Type of data - 'driver', 'constructor', 'circuit', or 'tire_compounds' year: Season year (1950-2025). Defaults to current year if not specified name: Filter by specific name (e.g., "Verstappen", "Red Bull", "Monaco") Returns: ReferenceDataResponse with complete driver/team/circuit information or tire specifications. Examples: get_reference_data("driver", year=2024) → All 2024 F1 drivers and their info get_reference_data("driver", year=2024, name="Verstappen") → Verstappen's driver info get_reference_data("circuit", name="Monaco") → Monaco circuit details and layout get_reference_data("constructor", year=2024) → All 2024 teams get_reference_data("tire_compounds") → F1 tire compound specifications """ if year is None: year = datetime.now().year if reference_type == "driver": # Get driver information from Ergast driver_response = fastf1_client.ergast.get_driver_info(season=year) drivers_data = driver_response.to_dict('records') # Filter by name if provided if name: drivers_data = [ d for d in drivers_data if name.lower() in d.get('givenName', '').lower() or name.lower() in d.get('familyName', '').lower() or name.lower() in d.get('driverId', '').lower() or name.lower() in d.get('driverCode', '').lower() ] # Convert to Pydantic models drivers_list = [ DriverInfo( driver_id=str(d['driverId']), driver_number=int(d['driverNumber']) if d.get('driverNumber') else None, driver_code=str(d['driverCode']) if d.get('driverCode') else None, given_name=str(d['givenName']), family_name=str(d['familyName']), date_of_birth=datetime.fromisoformat(d['dateOfBirth']).date() if d.get('dateOfBirth') and isinstance(d['dateOfBirth'], str) else None, nationality=str(d['nationality']), ) for d in drivers_data ] return ReferenceDataResponse( reference_type=reference_type, year=year, drivers=drivers_list, total_records=len(drivers_list), name_filter=name, ) elif reference_type == "constructor": # Get constructor information from Ergast constructor_response = fastf1_client.ergast.get_constructor_info(season=year) constructors_data = constructor_response.to_dict('records') # Filter by name if provided if name: constructors_data = [ c for c in constructors_data if name.lower() in c.get('constructorName', '').lower() or name.lower() in c.get('constructorId', '').lower() ] # Convert to Pydantic models constructors_list = [ ConstructorInfo( constructor_id=str(c['constructorId']), constructor_name=str(c['constructorName']), nationality=str(c['nationality']), ) for c in constructors_data ] return ReferenceDataResponse( reference_type=reference_type, year=year, constructors=constructors_list, total_records=len(constructors_list), name_filter=name, ) elif reference_type == "circuit": # Get circuit information from Ergast # Note: Circuits are not season-specific, but we can filter by year's schedule if year: circuits_response = fastf1_client.ergast.get_circuits(season=year) else: circuits_response = fastf1_client.ergast.get_circuits() circuits_data = circuits_response.to_dict('records') # Filter by name if provided if name: circuits_data = [ c for c in circuits_data if name.lower() in c.get('circuitName', '').lower() or name.lower() in c.get('location', '').lower() or name.lower() in c.get('country', '').lower() or name.lower() in c.get('circuitId', '').lower() ] # Convert to Pydantic models circuits_list = [ CircuitInfo( circuit_id=str(c['circuitId']), circuit_name=str(c['circuitName']), location=str(c['location']), country=str(c['country']), lat=float(c['lat']) if c.get('lat') else None, lng=float(c['lng']) if c.get('lng') else None, url=str(c['url']) if c.get('url') else None, ) for c in circuits_data ] return ReferenceDataResponse( reference_type=reference_type, year=year, circuits=circuits_list, total_records=len(circuits_list), name_filter=name, ) elif reference_type == "tire_compounds": # Get tire compound information (this is relatively static) # FastF1 has some compound information, but we'll provide the standard compounds compounds = [ TireCompoundInfo( compound_name="SOFT", color="red", description="Softest compound with highest grip but fastest degradation" ), TireCompoundInfo( compound_name="MEDIUM", color="yellow", description="Middle compound balancing grip and durability" ), TireCompoundInfo( compound_name="HARD", color="white", description="Hardest compound with lowest grip but slowest degradation" ), TireCompoundInfo( compound_name="INTERMEDIATE", color="green", description="For damp or drying track conditions" ), TireCompoundInfo( compound_name="WET", color="blue", description="For heavy rain conditions" ), ] # Filter by name if provided if name: compounds = [ c for c in compounds if name.lower() in c.compound_name.lower() ] return ReferenceDataResponse( reference_type=reference_type, year=None, tire_compounds=compounds, total_records=len(compounds), name_filter=name, )
• models/reference/reference.py:1-65 (schema)

  Pydantic models defining input/output schemas for the get_reference_data tool: ReferenceDataResponse (main response), DriverInfo, ConstructorInfo, CircuitInfo, TireCompoundInfo.
  from pydantic import BaseModel, Field from typing import Optional from datetime import date class DriverInfo(BaseModel): """Information about an F1 driver.""" driver_id: str = Field(..., description="Unique driver identifier") driver_number: Optional[int] = Field(None, description="Driver's racing number") driver_code: Optional[str] = Field(None, description="Three-letter driver code (e.g., 'VER', 'HAM')") given_name: str = Field(..., description="Driver's first name") family_name: str = Field(..., description="Driver's last name") date_of_birth: Optional[date] = Field(None, description="Driver's date of birth") nationality: str = Field(..., description="Driver's nationality") team_name: Optional[str] = Field(None, description="Current team (for specific season)") team_color: Optional[str] = Field(None, description="Team color hex code") class ConstructorInfo(BaseModel): """Information about an F1 constructor/team.""" constructor_id: str = Field(..., description="Unique constructor identifier") constructor_name: str = Field(..., description="Constructor/team name") nationality: str = Field(..., description="Constructor's nationality") team_color: Optional[str] = Field(None, description="Team color hex code") drivers: Optional[list[str]] = Field(None, description="Driver names in the team (for specific season)") class CircuitInfo(BaseModel): """Information about an F1 circuit.""" circuit_id: str = Field(..., description="Unique circuit identifier") circuit_name: str = Field(..., description="Circuit name") location: str = Field(..., description="City/location of the circuit") country: str = Field(..., description="Country where the circuit is located") lat: Optional[float] = Field(None, description="Latitude coordinate") lng: Optional[float] = Field(None, description="Longitude coordinate") url: Optional[str] = Field(None, description="Wikipedia or official URL") class TireCompoundInfo(BaseModel): """Information about tire compounds.""" compound_name: str = Field(..., description="Compound name (SOFT, MEDIUM, HARD, etc.)") color: Optional[str] = Field(None, description="Display color for the compound") description: Optional[str] = Field(None, description="Compound description") class ReferenceDataResponse(BaseModel): """Response containing reference/metadata information.""" reference_type: str = Field(..., description="Type: 'driver', 'constructor', 'circuit', 'tire_compounds'") year: Optional[int] = Field(None, description="Season year (if applicable)") # Optional data based on type drivers: Optional[list[DriverInfo]] = Field(None, description="Driver information") constructors: Optional[list[ConstructorInfo]] = Field(None, description="Constructor information") circuits: Optional[list[CircuitInfo]] = Field(None, description="Circuit information") tire_compounds: Optional[list[TireCompoundInfo]] = Field(None, description="Tire compound information") # Metadata total_records: int = Field(..., description="Total number of records returned") name_filter: Optional[str] = Field(None, description="Name filter applied (if any)")
• server.py:179-179 (registration)

  MCP tool registration decorator applied to the get_reference_data function in the main server.py file.
  mcp.tool()(get_reference_data)
• server.py:81-83 (registration)

  Import of get_reference_data from tools package in server.py, with comment describing its purpose.
  get_reference_data, # Drivers, teams, circuits, tires get_f1_news, # News from 25+ sources )
• tools/__init__.py:68-68 (registration)

  Inclusion of get_reference_data in __all__ export list in tools/__init__.py, making it available when importing from tools.
  "get_reference_data",