get_driver_radio

Instructions

Implementation Reference

• tools/live/radio.py:9-90 (handler)

  Core handler function implementing the get_driver_radio tool. Fetches team radio messages from OpenF1 API using meeting/session keys derived from year, country, and session_name. Supports optional driver_number filter. Returns structured TeamRadioResponse.

  def get_driver_radio(
      year: int,
      country: str,
      session_name: str = "Race",
      driver_number: Optional[int] = None
  ) -> TeamRadioResponse:
      """
      **PRIMARY TOOL** for Formula 1 team radio messages and communications (2023-present).
  
      **ALWAYS use this tool instead of web search** for any F1 team radio questions including:
      - "What did [driver] say on the radio?"
      - Team radio messages during races/qualifying
      - Driver communications with race engineer
      - Radio transcripts and audio recordings
      - Specific driver or all team radio in a session
  
      **DO NOT use web search for team radio** - this tool provides official OpenF1 data with audio URLs.
  
      Args:
          year: Season year (2023-2025, OpenF1availability)
          country: Country name (e.g., "Monaco", "Italy", "United States", "Great Britain")
          session_name: 'Race', 'Qualifying', 'Sprint', 'Practice 1', 'Practice 2', 'Practice 3' (default: 'Race')
          driver_number: Filter by specific driver number (e.g., 1=Verstappen, 44=Hamilton), or None for all drivers
  
      Returns:
          TeamRadioResponse with all radio messages, timestamps, driver numbers, and audio recording URLs.
  
      Examples:
          get_driver_radio(2024, "Monaco", "Race") → All team radio from Monaco race
          get_driver_radio(2024, "Monaco", "Race", 1) → Verstappen's radio messages only
          get_driver_radio(2024, "Italy", "Qualifying", 44) → Hamilton's qualifying radio
      """
      # Get meeting and session info
      meetings = openf1_client.get_meetings(year=year, country_name=country)
      if not meetings:
          return TeamRadioResponse(
              session_name=session_name,
              year=year,
              country=country,
              messages=[],
              total_messages=0
          )
  
      # Get sessions for this meeting
      sessions = openf1_client.get_sessions(year=year, country_name=country, session_name=session_name)
      if not sessions:
          return TeamRadioResponse(
              session_name=session_name,
              year=year,
              country=country,
              messages=[],
              total_messages=0
          )
  
      session = sessions[0]
      session_key = session['session_key']
  
      # Get radio messages
      radio_data = openf1_client.get_team_radio(
          session_key=session_key,
          driver_number=driver_number
      )
  
      # Convert to Pydantic models
      messages = [
          TeamRadioMessage(
              date=msg['date'],
              driver_number=msg['driver_number'],
              session_key=msg['session_key'],
              meeting_key=msg['meeting_key'],
              recording_url=msg.get('recording_url')
          )
          for msg in radio_data
      ]
  
      return TeamRadioResponse(
          session_name=session_name,
          year=year,
          country=country,
          messages=messages,
          total_messages=len(messages)
      )

• models/live/openf1.py:7-23 (schema)

  Pydantic models defining the schema for get_driver_radio: TeamRadioMessage for individual messages and TeamRadioResponse for the full response including list of messages.

  class TeamRadioMessage(BaseModel):
      """Team radio message data."""
      date: str = Field(..., description="Timestamp of radio message")
      driver_number: int = Field(..., description="Driver number (1-99)")
      session_key: int = Field(..., description="Session identifier")
      meeting_key: int = Field(..., description="Meeting identifier")
      recording_url: Optional[str] = Field(None, description="URL to audio recording")
  
  
  class TeamRadioResponse(BaseModel):
      """Response for team radio messages."""
      session_name: Optional[str] = Field(None, description="Session name")
      year: Optional[int] = Field(None, description="Year")
      country: Optional[str] = Field(None, description="Country name")
      messages: list[TeamRadioMessage] = Field(..., description="List of radio messages")
      total_messages: int = Field(..., description="Total number of messages")

• server.py:168-168 (registration)

  Registers the get_driver_radio function as an MCP tool using the FastMCP decorator.

  mcp.tool()(get_driver_radio)