Skip to main content
Glama

MCP Sport — F1 Telemetry MCP šŸŽļø

Animated race replay

An MCP (Model Context Protocol) server that exposes Formula 1 data from the OpenF1 API as tools for AI assistants (Claude Desktop, Cursor, MCP Inspector, etc.).

Full coverage: 18 data tools matching the 18 documented OpenF1 endpoints — sessions, meetings, drivers, results, laps, pit stops, stints, telemetry, weather, championships and more. Two MCP App views sit on top of that data: a drivers standings board and an animated race replay. Hosts that render MCP Apps show the HTML. Cursor and Claude Desktop do not: they return the same payload as JSON.

Stack

Layer

Technology

Language

Python 3.13+

MCP framework

FastMCP 4.x

Validation

Pydantic v2

Data

OpenF1 API (REST, free for historical data 2023+)

Project management

uv + pyproject.toml

Transport

stdio

Related MCP server: OpenF1 MCP Server

Installation

# Clone and install dependencies
git clone https://github.com/andrequeiroz2/mcp-sport.git mcp-sport
cd mcp-sport
uv sync

Usage

Run the server (stdio)

.venv/bin/python src/mcp_sport/server.py

MCP Inspector (web UI to test the tools)

npx @modelcontextprotocol/inspector@latest .venv/bin/python src/mcp_sport/server.py

In the Inspector UI: transport STDIO, command .venv/bin/python, args src/mcp_sport/server.py → Connect.

Claude Desktop / Cursor

Add to the client's MCP configuration:

{
  "mcpServers": {
    "f1-telemetry": {
      "command": "/absolute/path/mcp-sport/.venv/bin/python",
      "args": ["/absolute/path/mcp-sport/src/mcp_sport/server.py"]
    }
  }
}

The 18 data tools work in both clients. The views do not render there.

Views (MCP Apps)

get_drivers_championship_view and get_race_replay_view return interactive HTML. Cursor and Claude Desktop are incompatible with MCP Apps: they ignore the UI and show the JSON payload. The MCP Inspector also treats the result as text.

The views were validated in the official basic-host from modelcontextprotocol/ext-apps. The server must be HTTP, with CORS exposing the MCP session headers. Otherwise the browser cannot complete the Streamable HTTP handshake.

Terminal 1 — MCP server on port 8765:

uv run python -c "
import uvicorn
from starlette.middleware import Middleware
from starlette.middleware.cors import CORSMiddleware
from mcp_sport.server import mcp

app = mcp.http_app(middleware=[Middleware(
    CORSMiddleware,
    allow_origins=['*'],
    allow_methods=['*'],
    allow_headers=['*'],
    expose_headers=['mcp-session-id', 'mcp-protocol-version'],
)])
uvicorn.run(app, host='127.0.0.1', port=8765)
"

Terminal 2 — basic-host (needs Node.js; npm start requires bun, so use tsx):

git clone --depth 1 https://github.com/modelcontextprotocol/ext-apps.git
cd ext-apps/examples/basic-host
npm install
npm run build
SERVERS='["http://127.0.0.1:8765/mcp"]' npx tsx serve.ts

Open http://localhost:8080 (sandbox on :8081) and call get_drivers_championship_view or get_race_replay_view. After a change to the view HTML, hard-refresh the page (Ctrl+Shift+R) before running the tool again. The host caches the ui:// resource.

Available tools (18)

Domain

Tool

Description

Navigation

get_sessions

Sessions (practice, qualifying, sprint, race)

get_meetings

Grand Prix and testing weekends

Registry

get_drivers

Drivers by session/meeting

Results

get_session_results

Final classification of a session

get_starting_grid

Starting grid

get_positions

Position history throughout a session

Race

get_laps

Lap times, sectors and speeds

get_pit_stops

Pit stops

get_stints

Stints and tyre compounds

get_intervals

Real-time gaps (leader and car ahead)

get_race_control

Flags, safety car, incidents

Context

get_weather

Track weather (per-minute samples)

get_overtakes

Overtakes

get_team_radio

Team radio excerpts (MP3)

Telemetry

get_car_data

Speed, RPM, gear, throttle, brake, DRS (~3.7 Hz)

get_location

Approximate car position on the circuit (~3.7 Hz)

Championships

get_drivers_championship

Drivers standings (beta)

get_teams_championship

Teams standings (beta)

Example conversation with the AI

"How many points did Norris score in the last two races?"

The AI orchestrates: get_sessions(session_type="Race") to discover recent sessions → get_session_results(session_key=..., driver_number=4) on each one.

Project structure

src/mcp_sport/
ā”œā”€ā”€ server.py           # Entrypoint: FastMCP instance + tool registration
ā”œā”€ā”€ exceptions.py       # Domain exceptions
ā”œā”€ā”€ logging_config.py   # Logging to stderr (stdout is the protocol channel)
ā”œā”€ā”€ clients/openf1.py   # Single OpenF1 HTTP client
ā”œā”€ā”€ schemas/            # Pydantic: input (BaseInput) and output per endpoint
ā”œā”€ā”€ validators/         # Business validations per endpoint
ā”œā”€ā”€ services/           # Orchestration per endpoint
ā”œā”€ā”€ tools/              # MCP tools (thin layer) per endpoint
└── apps/               # MCP App views (Custom HTML, ui:// resource)
    ā”œā”€ā”€ championship_view.py  # Drivers standings board
    └── race_replay_view.py   # Animated race replay

Canonical documentation

Document

Contents

docs/Technical_Reference.md

Stack, versions and official links (source of truth)

docs/Architectural_Design.md

Implementation patterns and procedure for new endpoints

docs/Logging_Strategy.md

Logging strategy (stderr + per-request telemetry)

tasks/

History of planned and executed tasks

Configuration

Variable

Default

Description

MCP_SPORT_LOG_LEVEL

INFO

Log level on stderr (DEBUG, INFO, WARNING, ERROR)

Known limitations

  • Historical data from 2023 onwards; real-time data requires a paid OpenF1 subscription

  • session_result and starting_grid return HTTP 404 until official results are published

  • Telemetry (car_data, location) returns 18–24k samples per session/driver. Narrow the call with range filters such as speed_min and date_from/date_to

  • Championship endpoints are in beta on OpenF1

License

MIT. OpenF1 is an unofficial project, not associated in any way with the Formula 1 companies.

Available Tools

20 tools
get_car_dataGet Car DataA

Fetch car telemetry (speed, rpm, gear, throttle, brake, DRS) from OpenF1.

Sampled at ~3.7 Hz — always narrow down with the range filters below (e.g., a single lap via date_from/date_to, or high-speed samples via speed_min) to keep responses usable.

ParametersJSON Schema
NameRequiredDescriptionDefault
date_toNo
drs_maxNo
drs_minNo
rpm_maxNo
rpm_minNo
date_fromNo
speed_maxNo
speed_minNo
n_gear_maxNo
n_gear_minNo
session_keyNoint | str — required, positive int or 'latest'. Session identifier; use get_sessions to discover it.
throttle_maxNo
throttle_minNo
driver_numberNoint — required, 1-99. Driver number for the season.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description carries the full load. It usefully discloses the ~3.7 Hz sampling rate and the resulting response-size hazard, which is real value beyond structured fields, but says nothing about pagination, hard limits, or required permissions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero filler, front-loading purpose first and the filtering imperative second. Every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need no explanation, and the description covers purpose, sampling behavior, and filtering strategy for a 14-parameter tool. The main gap is that it doesn't clarify which dimensions (session_key/driver_number) anchor the query.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 14%, so the description must compensate and largely does not. It enumerates the telemetry channels that map to the min/max filter pairs and gives example usage for date_from/date_to and speed_min, but leaves the other ten parameters' semantics (min vs max, date format, session_key values) unexplained.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (fetch) and resource (car telemetry) and enumerates the actual channels (speed, rpm, gear, throttle, brake, DRS). This clearly separates it from siblings like get_laps or get_positions, so an agent can pick it without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives actionable guidance to always narrow using range filters and provides concrete examples (single lap via date_from/date_to, high-speed samples via speed_min). It lacks explicit when-to-use-vs-sibling routing (e.g., get_location for position over time), so it stops just short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_driversGet DriversB

Fetch F1 drivers from OpenF1, filtered by session, meeting or identity fields.

ParametersJSON Schema
NameRequiredDescriptionDefault
full_nameNostr — optional, 1-200 chars. Driver full name.
last_nameNostr — optional, 1-100 chars. Driver last name.
team_nameNostr — optional, 1-100 chars. Team name.
first_nameNostr — optional, 1-100 chars. Driver first name.
meeting_keyNoint | str — optional, positive int or 'latest'. Meeting (Grand Prix weekend) identifier.
session_keyNoint | str — optional, positive int or 'latest'. Session identifier; 'latest' targets the current/most recent session.
country_codeNostr — optional, 3 letters, normalized to uppercase. Deprecated by OpenF1 (removed after the 2026 season).
name_acronymNostr — optional, exactly 3 letters (e.g., VER). Normalized to uppercase.
driver_numberNoint — optional, 1-99. Driver number for the season.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden, and it discloses almost nothing: it does not say what happens when no filters are supplied (all drivers?), whether filters combine as AND, whether results are paginated, or how 'latest' is interpreted. The only real behavioral hint is the upstream data source (OpenF1).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single tight sentence with the action and the filtering axes front-loaded; nothing is wasted, though there is also no supplementary structure such as notes on defaults.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With nine optional parameters and an output schema present, the description need not explain return values, but for a zero-annotation tool it leaves open the default no-filter behavior and filter combination semantics. Adequate but with clear gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so every parameter is already documented with type, length, and normalization rules; the description only groups them into 'session, meeting or identity fields' and adds no syntax or precedence detail beyond the schema. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Fetch') and resource ('F1 drivers from OpenF1') plus the supported filter dimensions, so the agent knows exactly what this returns. It does not compare itself to near neighbors like get_drivers_championship_view or get_session_results, so it falls short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'filtered by session, meeting or identity fields' implies when this tool is appropriate (slicing the driver roster), but there is no explicit when-to-use guidance, no exclusions, and no named alternative for adjacent needs such as championship standings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_drivers_championshipGet Drivers ChampionshipA

Fetch drivers championship standings from OpenF1 (beta endpoint).

Only available for race sessions. This endpoint is in beta: its behavior or fields may change without notice.

ParametersJSON Schema
NameRequiredDescriptionDefault
session_keyNoint | str — required in practice, positive int or 'latest'. Race session identifier; use get_sessions with session_type='Race' to discover it.
driver_numberNoint — optional, 1-99. Driver number for the season.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does disclose two meaningful traits: the tool only works for race sessions and the endpoint is beta with fields subject to change without notice. It omits auth requirements, rate limits, and the shape of returned standings, but the beta-volatility warning is genuinely useful context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences with the core action first and the qualifiers following; no filler and nothing redundant. Each sentence carries a distinct piece of information (what, availability constraint, stability caveat).

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return-value details need not be described, and parameters are fully covered by the schema. The description covers availability and stability, but nothing explains how the returned standings differ from the 'view' variant, which is the main remaining ambiguity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters (session_key, driver_number) are already fully documented in the schema, including the 'latest' sentinel and the discovery path. The description adds no parameter meaning beyond that, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Fetch drivers championship standings') plus the data source (OpenF1), which is unambiguous. However, it does not distinguish itself from the sibling 'get_drivers_championship_view', so an agent cannot tell the two apart from the description alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Only available for race sessions' is an explicit precondition for use, and the schema further routes the agent to get_sessions with session_type='Race' for discovery. It gives clear context but no explicit exclusion or comparison against the near-identical 'view' sibling.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_drivers_championship_viewGet Drivers Championship ViewA

Fetch drivers championship standings and render them as a visual board.

MCP App spike (task 05): in hosts supporting the MCP Apps extension, the result renders as an interactive HTML board with driver photos, team colors and points. In other hosts, the same data is returned as JSON text.

ParametersJSON Schema
NameRequiredDescriptionDefault
session_keyNoint | str — required in practice, positive int or 'latest'. Race session identifier; use get_sessions with session_type='Race' to discover it.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden, and it discloses a genuinely non-obvious trait: output format varies by host (interactive HTML board in MCP Apps hosts, JSON text elsewhere). It omits auth/permission requirements and error behavior, but for a read of public standings the host-dependency caveat is the key behavioral fact.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the core action and followed by the host-specific rendering note; nothing is padded. The internal reference 'MCP App spike (task 05)' is developer-facing jargon that adds little for an agent, a minor blemish on an otherwise tight description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained, and the description covers the one thing the schema can't: host-dependent rendering. The remaining gap is the lack of an explicit contrast with the get_drivers_championship sibling, which an agent choosing between them would want.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%: session_key is fully documented in the schema, including its type union, the 'latest' sentinel, and the get_sessions discovery path. The description adds no parameter-level meaning, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

It states a specific verb ('fetch') and resource ('drivers championship standings') and adds a distinct second verb ('render them as a visual board') that implicitly separates it from the data-only sibling get_drivers_championship. It stops short of naming that sibling explicitly, so an agent must infer the view-vs-data split.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by 'render them as a visual board' and by the host-support caveat, which tells the agent what to expect in different hosts. However, it never states when to prefer this tool over get_drivers_championship or get_race_replay_view, and offers no exclusions or preconditions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_intervalsGet IntervalsA

Fetch real-time gaps between drivers and to the race leader from OpenF1.

Available during races only, with updates approximately every 4 seconds. Use date_from/date_to to bound the response (e.g., the closing laps).

ParametersJSON Schema
NameRequiredDescriptionDefault
date_toNo
date_fromNo
session_keyNoint | str — required in practice, positive int or 'latest'. Session identifier; use get_sessions to discover it.
driver_numberNoint — optional, 1-99. Driver number for the season.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does disclose meaningful behavior: the real-time cadence (~4 second updates) and the race-only availability window. It stops short of explaining error behavior outside a race or any return/pagination characteristics, so it is good but not complete.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences, front-loaded with the core purpose, then availability, then a parameter tip. No filler and every sentence carries usable information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given an output schema already covers return values, the description supplies what remains needed: what the tool returns conceptually (gaps), when it is available, how fresh the data is, and how to bound it. Nothing critical for correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 50%: session_key and driver_number are documented in the schema, while date_from/date_to are not. The description compensates for exactly that gap by explaining that the date parameters bound the response (e.g., closing laps), adding semantics the schema omits.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Fetch') and a well-defined resource ('real-time gaps between drivers and to the race leader'), which cleanly distinguishes it from siblings like get_positions or get_laps. It doesn't explicitly name a sibling it is not, but the resource is described precisely enough that an agent can differentiate it.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Available during races only' gives a genuine availability condition, and the date_from/date_to hint suggests a bounding strategy. However, it never routes the agent to or away from a specific alternative (e.g., get_positions for standing) and offers no explicit when-not guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_lapsGet LapsC

Fetch detailed lap-by-lap data for an F1 session from OpenF1.

ParametersJSON Schema
NameRequiredDescriptionDefault
date_toNo
date_fromNo
lap_numberNoint — optional, >= 1. Exact lap number (do not combine with lap_number_min/max).
session_keyNoint | str — required in practice, positive int or 'latest'. Session identifier; use get_sessions to discover it.
i1_speed_maxNo
i1_speed_minNo
i2_speed_maxNo
i2_speed_minNo
st_speed_maxNo
st_speed_minNo
driver_numberNoint — optional, 1-99. Driver number for the season.
lap_number_maxNo
lap_number_minNo
lap_duration_maxNo
lap_duration_minNo
duration_sector_1_maxNo
duration_sector_1_minNo
duration_sector_2_maxNo
duration_sector_2_minNo
duration_sector_3_maxNo
duration_sector_3_minNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden. Beyond the word 'Fetch' implying a read, it discloses nothing about pagination, result limits, permission/auth needs, or default scoping for unfiltered queries on a 21-parameter tool. The output schema softens the return-value gap but not the rest.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no wasted words and the resource stated first. It is structurally clean, though its terseness borders on under-specification rather than optimal economy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 21-parameter, annotation-free query tool, one generic sentence is far too thin. The presence of an output schema excuses it from explaining return values, but nothing addresses how to combine or select among the many filters, when session_key is effectively required, or how this differs from sibling tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 14% (roughly 3 of 21 parameters documented), and the description adds no meaning for any filter parameter. It does not explain the speed/sector/duration min-max pairs, the lap_number vs lap_number_min/max exclusivity, or the driver_number/date filtering, leaving most parameters semantically opaque.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Fetch detailed lap-by-lap data for an F1 session from OpenF1'), which is clear. However, it does not differentiate from siblings such as get_stints or get_pit_stops, which also return lap-derived session data, so an agent gets no routing signal from the description alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no mention of prerequisites (e.g., discovering session_key via get_sessions, which the schema hints at), and no explicit alternatives among the many sibling tools. The only context is the implied 'for an F1 session' scope.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_locationGet LocationA

Fetch approximate car positions on the circuit from OpenF1.

Sampled at ~3.7 Hz — always narrow down with date_from/date_to (e.g., a single lap) to keep responses usable. Useful for gauging progress along the track, but lacks lateral placement (left/right side). The origin point (0, 0, 0) is arbitrary.

ParametersJSON Schema
NameRequiredDescriptionDefault
x_maxNo
x_minNo
y_maxNo
y_minNo
z_maxNo
z_minNo
date_toNo
date_fromNo
session_keyNoint | str — required, positive int or 'latest'. Session identifier; use get_sessions to discover it.
driver_numberNoint — required, 1-99. Driver number for the season.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden and delivers: ~3.7 Hz sample rate, the volume implication requiring narrow ranges, lack of lateral placement, and an arbitrary origin. It omits any auth/permission or auth-requirement notes but discloses the salient data-shape traits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four tight sentences, front-loaded with the core purpose, then the sampling/volume caveat, then coordinate limitations. Every sentence earns its place with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return values need not be explained, and the description covers the key caveats (sampling rate, coordinate limits, arbitrary origin) needed to interpret results. The main gap is the undocumented bounding-box filters, but for a data-fetch tool this is largely complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 20%, so the description must compensate. It meaningfully explains date_from/date_to usage and the arbitrary (0,0,0) origin that gives x/y/z coordinate context, but the six x_min/x_max/y_min/y_max/z_min/z_max bounding-box parameters are left undefined in both schema and description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Fetch) and resource (approximate car positions on the circuit) plus the data source (OpenF1). It implicitly distinguishes from get_positions by clarifying these are on-track coordinates rather than standings, though it never names that sibling explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear operational guidance: always narrow with date_from/date_to (e.g., a single lap) to keep responses usable. It lacks explicit when-not conditions or named alternatives, but tells the agent how to use the tool effectively.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_meetingsGet MeetingsC

Fetch F1 meetings (Grand Prix or testing weekends) from OpenF1.

ParametersJSON Schema
NameRequiredDescriptionDefault
yearNoint — optional, >= 2023 (OpenF1 data starts in 2023).
locationNostr — optional, 1-100 chars, e.g., 'Marina Bay'.
circuit_keyNoint — optional, positive int. Circuit identifier.
meeting_keyNoint | str — optional, positive int or 'latest'. Meeting identifier; 'latest' targets the current/most recent meeting.
country_nameNostr — optional, 1-100 chars, e.g., 'Singapore'.
meeting_nameNostr — optional, 1-100 chars, e.g., 'Singapore Grand Prix'.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden. It implies a read operation by the word 'Fetch' and names the data source, but says nothing about filter-combination semantics, pagination, default scoping, or what happens when no filters are passed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, tight sentence with no filler, and the subject (meetings, with a clarifying parenthetical) is front-loaded. It is efficient but perhaps overly terse for a 6-parameter tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be described. However, for a tool with six optional filters and no annotations, the description does not explain filtering behavior or how the tool relates to its siblings, leaving meaningful gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so every parameter is already documented in the schema with type, range, and examples. The description adds nothing beyond that, so the baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Fetch') and resource ('F1 meetings') and usefully clarifies domain jargon by defining a meeting as a Grand Prix or testing weekend. However, it does not distinguish this tool from siblings like get_sessions, which an agent would need in order to pick correctly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description offers no guidance on when to use this tool versus the many sibling tools (get_sessions, get_starting_grid, etc.). There is no mention of alternatives or of how the optional filters should be combined.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_overtakesGet OvertakesA

Fetch overtakes during F1 races from OpenF1.

Covers on-track passes and position changes from pit stops or post-race penalties. Only available during races and may be incomplete.

ParametersJSON Schema
NameRequiredDescriptionDefault
positionNoint — optional, >= 1. Position of the overtaking driver after the overtake.
session_keyNoint | str — required in practice, positive int or 'latest'. Race session identifier; use get_sessions to discover it.
overtaken_driver_numberNoint — optional, 1-99. The passed driver.
overtaking_driver_numberNoint — optional, 1-99. The attacking driver.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.8/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the behavioral burden and does so reasonably: it discloses the availability window, that results "may be incomplete," and what event types are covered. It omits auth/rate-limit details, but for a read-only data fetch the disclosed caveats are the material ones.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, front-loaded with the resource and immediately followed by scope and constraints. No filler or repetition of the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need no explanation, and the description supplies the key caveats (availability window, possible incompleteness). It could be stronger by noting relationships to get_sessions or get_positions, but it is essentially complete for calling the tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all four parameters, including that session_key is "required in practice" and to use get_sessions. The description adds no parameter meaning beyond that, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ("Fetch overtakes during F1 races") and defines the scope (on-track passes, pit-stop and penalty position changes), which is distinct from siblings like get_positions or get_laps. It does not explicitly contrast itself with any sibling, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a genuine availability condition ("Only available during races") and a reliability caveat, which helps the agent decide when results are meaningful. However, it names no alternative tool and offers no explicit when-to-use-vs-get_positions routing, so guidance is only implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_pit_stopsGet Pit StopsC

Fetch pit lane passes for an F1 session from OpenF1.

ParametersJSON Schema
NameRequiredDescriptionDefault
date_toNo
date_fromNo
lap_numberNoint — optional, >= 1. Exact lap of the stop (do not combine with lap_number_min/max).
session_keyNoint | str — required in practice, positive int or 'latest'. Session identifier; use get_sessions to discover it.
driver_numberNoint — optional, 1-99. Driver number for the season.
lap_number_maxNo
lap_number_minNo
lane_duration_maxNo
lane_duration_minNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden. Only 'Fetch' implies a read operation; it does not disclose the practical need for session_key, permissions, pagination, filtering behavior, or side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One front-loaded sentence with no padding. It is concise, though that conciseness reflects under-specification rather than completeness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return values need not be described, but for a 9-parameter tool with no annotations and low schema coverage, the description omits required session_key context, usage guidance, and parameter semantics.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has 9 parameters, but schema description coverage is only 33%, and the description adds no parameter meaning. It does not compensate for undocumented filters like lane_duration_min/max or lap_number_min/max.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb 'Fetch' and resource 'pit lane passes' with scope 'F1 session' and source 'OpenF1', so the tool's purpose is clear. It does not distinguish itself from sibling data tools such as get_laps or get_stints.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit when-to-use, when-not, or alternative tool guidance. The phrase 'for an F1 session' implies context but does not tell an agent when to choose this tool over siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_positionsGet PositionsC

Fetch driver position changes throughout an F1 session from OpenF1.

ParametersJSON Schema
NameRequiredDescriptionDefault
date_toNo
positionNoint — optional, >= 1. Exact position (do not combine with position_min/max).
date_fromNo
meeting_keyNoint | str — optional, positive int or 'latest'. Meeting (Grand Prix weekend) identifier.
session_keyNoint | str — optional, positive int or 'latest'. Session identifier; use get_sessions to discover it.
position_maxNo
position_minNo
driver_numberNoint — optional, 1-99. Driver number for the season.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden. It discloses only that data represents 'changes' across a session; it says nothing about pagination, ordering, data volume, or auth/rate-limit behavior for what is likely a large time-series payload. This is thin for a tool with zero annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler, so nothing is wasted. It is arguably under-specified rather than concise, but structurally it is clean and immediately readable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 8 optional parameters, no annotations, and no guidance on parameter combinations (e.g., that exact position conflicts with position_min/max, or how date ranges interact), the description is too sparse. The existence of an output schema excuses it from explaining return values, but the invocation guidance is still incomplete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 50%: position, meeting_key, session_key, and driver_number are documented in the schema, but date_to, date_from, position_max, and position_min are bare. The description adds no parameter meaning at all, so it fails to compensate for the undocumented half, including the position_min/max range semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb ('fetch') and resource ('driver position changes throughout an F1 session'), which is more precise than a tautology and hints at time-series change data rather than a static grid. It does not, however, explicitly distinguish itself from near neighbors like get_starting_grid or get_session_results, so sibling differentiation is left to inference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no when-not-to-use, and no mention of alternatives among the many position-related siblings. The phrase 'throughout an F1 session' is the only contextual hint, leaving an agent to guess whether this or get_starting_grid is appropriate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_race_controlGet Race ControlC

Fetch race control events (flags, safety car, incidents) from OpenF1.

ParametersJSON Schema
NameRequiredDescriptionDefault
flagNostr — optional, 1-50 chars, e.g., 'YELLOW', 'BLACK AND WHITE'. Normalized to uppercase.
scopeNostr — optional, e.g., 'Track', 'Driver', 'Sector'.
date_toNo
categoryNostr — optional, e.g., 'SessionStatus', 'CarEvent', 'Drs', 'Flag', 'SafetyCar'.
date_fromNo
session_keyNoint | str — optional, positive int or 'latest'. Session identifier; use get_sessions to discover it.
driver_numberNoint — optional, 1-99. Driver number for the season.
lap_number_maxNo
lap_number_minNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description carries the full behavioral burden, and it discloses almost nothing beyond the resource name. It doesn't state that this is a read-only query, that every parameter is optional and unfiltered calls may return large result sets, or that session_key accepts 'latest' — the schema hints at that but the description does not reinforce it.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler; the resource and its content are stated immediately. Brevity here borders on under-specification for a 9-parameter tool, but nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return values need not be explained, but with 9 parameters, no annotations, and half the schema undocumented, the description leaves the agent without enough context to filter correctly or understand behavior. It is far too thin for the tool's surface area.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 56% and four parameters (date_from, date_to, lap_number_min, lap_number_max) have no schema description at all, so the description is expected to compensate. Instead it names zero parameters, and its 'flags / safety car' examples only loosely echo category and flag values already documented in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Fetch') and resource ('race control events') and clarifies the payload with examples (flags, safety car, incidents). It's clear what the tool returns, though it makes no attempt to distinguish itself from siblings like get_overtakes or get_session_results.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions. With 9 optional filters and a 'latest' session option, an agent gets no help deciding between a filtered call and a broad one.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_race_replay_viewGet Race Replay ViewA

Replay a race as an animated position chart (bar-chart-race style).

MCP App (task 06): in hosts supporting the MCP Apps extension, renders cars stacked by official position with a checkered treadmill paced by the leader (a new lap opens when the leader crosses), tyre compound badges (red S / yellow M / white H), per-sector times with broadcast colors recomputed at the displayed instant (one purple per sector, green = personal best, yellow = slower), the lap time as MM:SS:mmm, PIT badges, a centered Safety Car / VSC / race-suspended banner, and a header with circuit, local start time and track conditions. Retired cars show a permanent OUT or DNS tag and drop gap, sectors and lap time. In other hosts the same payload is returned as JSON text.

ParametersJSON Schema
NameRequiredDescriptionDefault
session_keyNoint | str — optional, positive int or 'latest'. Defaults to 'latest' when omitted. RACE session identifier; use get_sessions with session_type='Race' to discover it. During a live race, 'latest' yields a snapshot of the data available so far.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does disclose meaningful behavior: host-dependent rendering (MCP Apps extension vs. JSON fallback), live snapshot handling, and how retired/DNS cars, safety-car banners, and pit badges are treated. It does not mention cost, latency, or that the payload is large, but the host-dependent output behavior is genuinely useful context beyond the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded in one clean sentence, but the following run-on sentence enumerates UI minutiae (tyre badge colors, per-sector color rules, MM:SS:mmm formatting) that do not help an agent select or invoke the tool. Roughly half the text is rendering detail rather than invocation-relevant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return-value explanation is not required, and the description instead covers the host-dependent rendering path and fallback, which the schema cannot express. Combined with the richly documented parameter, an agent has enough to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single session_key parameter already documents the int|'latest' semantics, default, and live-snapshot behavior. The description adds nothing about the parameter, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence names a specific verb (replay) and resource (a race) and states the output form (animated bar-chart-race position chart), which is distinct from the raw-data siblings like get_positions or get_laps. It stops short of explicitly naming which sibling to use instead, so an agent must infer the distinction from the word 'chart'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: the description suggests this is for visual playback rather than data retrieval, but it never states when to prefer it over get_positions/get_laps or that the raw data is unavailable here. No exclusions or prerequisites are given, leaving the agent to guess the selection rule.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_session_resultsGet Session ResultsA

Fetch the final classification of an F1 session from OpenF1.

Results become available a few minutes after the official results are published on the Formula 1 website. If the API returns HTTP 404, the results are not yet published for that session — retry with an earlier session_key (use get_sessions to find completed sessions).

ParametersJSON Schema
NameRequiredDescriptionDefault
positionNoint — optional, >= 1. Final position in the session.
session_keyNoint | str — required in practice, positive int or 'latest'. Session identifier; use get_sessions to discover it.
driver_numberNoint — optional, 1-99. Driver number for the season.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.9/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations, so the description carries the burden, and it does so well: it discloses data-availability timing (delayed a few minutes), HTTP 404 semantics, and a retry strategy. It doesn't cover auth, rate limits, or pagination, but for a read tool this is meaningful behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the one-line purpose, then adds behavioral notes. No filler; every sentence (availability timing, 404 handling) earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return values need not be explained, and the description covers purpose, availability timing, and error handling. Adequate for a 3-param read tool, though auth/permission context is absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all three parameters are already documented, including session_key being required in practice and discoverable via get_sessions. The description reinforces the session_key discovery path but adds nothing about position or driver_number beyond the schema. Baseline 3 is correct.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource: 'Fetch the final classification of an F1 session.' The word 'final' scopes it away from live-position tools like get_positions, giving implicit sibling differentiation, though no sibling is named explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete context: results appear a few minutes after official publication, and on 404 the agent should retry with an earlier session_key. It names get_sessions as the way to find completed sessions. Missing an explicit when-not-to-use statement, but the guidance is actionable.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_sessionsGet SessionsB

Fetch F1 sessions (practice, qualifying, sprint, race) from OpenF1.

ParametersJSON Schema
NameRequiredDescriptionDefault
yearNoint — optional, >= 2023 (OpenF1 data starts in 2023).
locationNostr — optional, 1-100 chars, e.g., 'Spa-Francorchamps'.
circuit_keyNoint — optional, positive int. Circuit identifier.
meeting_keyNoint | str — optional, positive int or 'latest'. Meeting (Grand Prix weekend) identifier.
session_keyNoint | str — optional, positive int or 'latest'. Session identifier; 'latest' targets the current/most recent session.
country_nameNostr — optional, 1-100 chars, e.g., 'Belgium'.
session_nameNostr — optional, e.g., 'Practice 1', 'Qualifying', 'Race'.
session_typeNostr — optional, e.g., 'Practice', 'Qualifying', 'Race'.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden, and it offers almost nothing beyond 'Fetch'. It does not state that this is a read-only lookup, how multiple filters combine (AND vs OR), how 'latest' is resolved, or any pagination/ordering behavior. No contradiction, but a significant disclosure gap for an 8-param query tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single tight sentence, front-loaded with the verb and resource plus a useful parenthetical scope. No filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained. However, with 8 optional filters, no annotations, and no statement about how filters interact or when this tool is the right entry point versus get_meetings/get_session_results, the definition is only minimally complete for an agent to select and call it confidently.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with each parameter documented in the schema (ranges, examples such as 'Spa-Francorchamps', 'latest' semantics), so the schema does the heavy lifting. The description adds no parameter meaning beyond that, making the baseline 3 appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Fetch') and resource ('F1 sessions') and clarifies the domain concept by enumerating session kinds (practice, qualifying, sprint, race). It does not, however, distinguish itself from nearby siblings like get_meetings or get_session_results, which an agent must infer from the name alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this versus alternatives such as get_meetings (weekend-level) or get_session_results (results within a session). Usage is only implied by the resource name; there are no exclusions, prerequisites, or filter-combination hints.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_starting_gridGet Starting GridA

Fetch the starting grid for an F1 race from OpenF1.

Grid data becomes available a few minutes after the official results are published on the Formula 1 website. If the API returns HTTP 404, the grid is not yet published for that session — retry with an earlier session_key (use get_sessions to find completed sessions).

ParametersJSON Schema
NameRequiredDescriptionDefault
positionNoint — optional, >= 1. Position on the grid.
session_keyNoint | str — required in practice, positive int or 'latest'. Session identifier; use get_sessions to discover it.
driver_numberNoint — optional, 1-99. Driver number for the season.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.9/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the behavioral burden, and it does so well by disclosing data-availability timing and the 404 failure mode plus the correct recovery action. It omits whether results are paginated or how a partial grid is returned, but the availability/error semantics are the operationally important traits for this endpoint.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the one-line purpose, then adds two short paragraphs of operational guidance with no filler. Slightly longer than strictly necessary, but every sentence conveys actionable information about timing or error handling.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return-value explanation is not needed, and the description covers the two things an agent would otherwise guess wrong: when grid data becomes available and what a 404 means. Auth and rate-limit behavior are unaddressed, but the core call-and-recover loop is complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all three parameters (position, session_key, driver_number) are already documented in the schema, including the 'latest' enum-like value and the get_sessions discovery pointer. The description adds no syntax or format detail beyond what the schema provides, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Fetch the starting grid for an F1 race from OpenF1"), which is unambiguous. It does not, however, distinguish itself from adjacent siblings like get_session_results or get_positions, which return overlapping race data; the only sibling named (get_sessions) is cited for parameter discovery, not disambiguation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives real conditional guidance: grid data appears a few minutes after official results, and HTTP 404 means the grid isn't published yet, so the agent should retry with an earlier session_key. It stops short of stating when to prefer this tool over get_session_results/get_positions for grid information.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_stintsGet StintsC

Fetch tyre stints (periods of continuous driving) from OpenF1.

ParametersJSON Schema
NameRequiredDescriptionDefault
compoundNostr — optional, 1-20 chars, e.g., 'SOFT', 'MEDIUM', 'HARD'. Normalized to uppercase.
lap_end_maxNo
lap_end_minNo
session_keyNoint | str — required in practice, positive int or 'latest'. Session identifier; use get_sessions to discover it.
stint_numberNoint — optional, >= 1. Sequential stint number.
driver_numberNoint — optional, 1-99. Driver number for the season.
lap_start_maxNo
lap_start_minNo
tyre_age_at_start_maxNo
tyre_age_at_start_minNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden. 'Fetch' implies a read-only operation but the description says nothing about pagination, result limits, ordering, or the practical requirement of a session_key.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single short sentence with no wasted words and the resource is front-loaded. It is appropriately terse but that terseness comes at the cost of substance rather than being efficiently informative.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter tool with no annotations, 40% schema coverage, and range filters whose semantics are undocumented, this is far too thin. The existence of an output schema covers return values, but nothing covers filtering behavior or how to scope a query.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Ten parameters with only 40% schema description coverage, and the description adds zero parameter meaning. Six of the ten params (all the *_min/*_max range filters) have no documentation in either the schema or the description, so an agent cannot tell how they combine.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Fetch) and resource (tyre stints) and helpfully defines the term as 'periods of continuous driving'. However it does nothing to distinguish this from closely related siblings like get_pit_stops or get_laps, so an agent must infer the boundary itself.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no mention of prerequisites, and no naming of alternatives. With 20 sibling data-fetch tools including pit stops and laps that overlap conceptually, the absence of routing guidance is a significant gap.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_team_radioGet Team RadioA

Fetch team radio exchanges between drivers and teams from OpenF1.

Only a limited selection of communications is included, not the complete record. Coverage has decreased significantly starting in 2026, with most events providing no radio data at all (a limitation on F1's side).

ParametersJSON Schema
NameRequiredDescriptionDefault
session_keyNoint | str — required in practice, positive int or 'latest'. Session identifier; use get_sessions to discover it.
driver_numberNoint — optional, 1-99. Driver number for the season.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.8/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It transparently discloses a critical limitation: only a limited selection of communications is included, and coverage has decreased significantly starting in 2026 with most events providing no radio data. This is valuable context beyond the schema. It does not mention read-only nature or other traits, but for a fetch tool this is a strong disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the core action. The second sentence efficiently delivers a critical caveat about data completeness. Every sentence earns its place, with no redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (2 parameters, output schema present, no annotations), the description provides the essential purpose and a key limitation. An agent has enough to call it correctly, though explicit usage guidance versus alternatives is absent. The output schema covers return values, so the description need not explain them.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents both parameters fully, including that session_key is 'required in practice' and how to discover it. The description adds no additional parameter syntax, format, or constraint information. Baseline 3 is correct when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Fetch') and resource ('team radio exchanges between drivers and teams from OpenF1'), making the purpose clear. It does not explicitly differentiate from siblings like get_race_control or get_weather, but the resource is unique enough that confusion is unlikely. A 4 is appropriate because it lacks the explicit sibling routing seen in top-tier definitions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage by stating what the tool fetches, but provides no explicit guidance on when to use it versus alternatives or when not to use it. The coverage limitation hint could serve as an implicit caution, but it is not framed as usage guidance. This is the minimum viable level.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_teams_championshipGet Teams ChampionshipA

Fetch teams championship standings from OpenF1 (beta endpoint).

Only available for race sessions. This endpoint is in beta: its behavior or fields may change without notice.

ParametersJSON Schema
NameRequiredDescriptionDefault
team_nameNostr — optional, 1-100 chars, e.g., 'McLaren'.
session_keyNoint | str — required in practice, positive int or 'latest'. Race session identifier; use get_sessions with session_type='Race' to discover it.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden. It usefully discloses the beta status and that fields may change without notice, plus the race-session-only restriction, but says nothing about auth, rate limits, or pagination behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, zero waste, with the primary purpose front-loaded and the caveats (race-only, beta) following in order of importance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be described. The description covers the key operational caveats (session type restriction, beta instability) an agent needs; only cross-tool routing guidance is absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and both parameters (team_name, session_key) are already documented in the schema including the 'latest' option and how to discover session_key. The description adds no parameter meaning beyond that, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (fetch) and resource (teams championship standings) from a named source (OpenF1), which cleanly separates it from the sibling get_drivers_championship. It does not explicitly name that sibling, so differentiation is implied by the word 'teams' rather than stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Only available for race sessions' gives a concrete when-to-use constraint that rules out practice/qualifying sessions. It stops short of naming an alternative or explaining what to do for non-race sessions, so it is clear context without explicit alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_weatherGet WeatherC

Fetch weather conditions over the track from OpenF1 (sampled every minute).

ParametersJSON Schema
NameRequiredDescriptionDefault
date_toNo
date_fromNo
meeting_keyNoint | str — optional, positive int or 'latest'. Meeting (Grand Prix weekend) identifier.
session_keyNoint | str — optional, positive int or 'latest'. Session identifier; use get_sessions to discover it.
humidity_maxNo
humidity_minNo
rainfall_maxNo
rainfall_minNo
wind_speed_maxNo
wind_speed_minNo
air_temperature_maxNo
air_temperature_minNo
track_temperature_maxNo
track_temperature_minNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations, so the description carries the full behavioral burden. It does disclose a meaningful trait — data sampled every minute — which tells the agent the resolution of the returned series. However, it omits access/scope prerequisites, how session_key and meeting_key interact, and whether unfiltered calls return everything or nothing useful.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single tight sentence with the source and cadence front-loaded and no filler. It is concise, though arguably too terse for a tool with 14 parameters and no other prose to carry the gaps.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return-value explanation is not needed. But with 14 optional parameters, 14% schema coverage, no annotations, and no usage guidance, the description is far too thin to let an agent understand how to scope a query or what the range filters do.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 14% — just meeting_key and session_key are documented, leaving 12 filter parameters (all the _min/_max range filters) unexplained. The description adds nothing about filtering semantics, so it fails to compensate for the coverage gap on a 14-parameter tool.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Fetch) and resource (weather conditions over the track), and names the data source (OpenF1) with sampling cadence. It's clearly distinct from siblings like get_laps or get_car_data, though it never explicitly differentiates itself or notes what weather fields are returned.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance, no mention of how to scope the query (meeting_key vs session_key vs date range), and no exclusions. An agent must infer from the schema alone which of the 14 optional filters to combine, with zero routing help.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 20 tool updatesv0.1.0
    • First observedget_car_data
    • First observedget_drivers
    • First observedget_drivers_championship
    • First observedget_drivers_championship_view
    • First observedget_intervals
    • First observedget_laps
    • First observedget_location
    • First observedget_meetings
    • First observedget_overtakes
    • First observedget_pit_stops
    • First observedget_positions
    • First observedget_race_control
    • First observedget_race_replay_view
    • First observedget_session_results
    • First observedget_sessions
    • First observedget_starting_grid
    • First observedget_stints
    • First observedget_team_radio
    • First observedget_teams_championship
    • First observedget_weather

TDQS

A3.5/5.0

Scored across 20 tools

Disambiguation4/5

Most tools target clearly distinct F1 data endpoints (weather, laps, pit stops, car data, etc.), but get_drivers_championship and get_drivers_championship_view fetch the same standings with different rendering, which could cause selection confusion. get_race_replay_view also partially overlaps with position/location tools, though its replay purpose is described distinctly.

Naming Consistency5/5

All tools follow a consistent get_<resource> snake_case pattern (e.g., get_weather, get_drivers, get_laps). The two view tools add a predictable _view suffix, so the naming remains coherent and readable.

Tool Count4/5

20 tools is on the heavy side, but the F1 data domain is broad and each tool maps to a distinct OpenF1 endpoint or presentation layer. The count is reasonable rather than bloated, though it could be tightened by merging the championship view with its data tool.

Completeness5/5

The set covers the full OpenF1 read-only surface: sessions, meetings, drivers, results, grids, positions, laps, pit stops, stints, intervals, race control, overtakes, radio, telemetry, location, and both championships. The added view tools provide optional rendering without leaving obvious gaps.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    B
    quality
    D
    maintenance
    Provides comprehensive Formula 1 data access including race schedules, session results, lap times, telemetry data, driver/constructor standings, and circuit information. Enables users to retrieve and analyze F1 racing data through natural language queries using the FastF1 Python package.
    5
    MIT
  • F
    license
    Not graded
    quality
    D
    maintenance
    Enables access to Formula 1 data from the openF1.org API, including driver information, race results, lap times, telemetry, pit stops, weather conditions, and live position data across multiple seasons.
    -
  • A
    license
    Not graded
    quality
    D
    maintenance
    Provides easy access to Formula 1 data including championship standings, event info, season calendars, track visualizations, session results, and driver/constructor info via FastF1 and OpenF1 API.
    1
    MIT
  • F
    license
    Not graded
    quality
    D
    maintenance
    A real-time Formula 1 analytics server that lets you ask natural language questions about races, lap times, tyre strategies, pit stops, and more using live data from the OpenF1 API.
    -