OpenF1 MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@OpenF1 MCP ServerWho won the 2025 São Paulo GP and how many positions did each driver gain?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
openf1-mcp
MCP server for the OpenF1 API — Formula 1 timing, telemetry and session data from 2023 onwards.
TypeScript, stdio transport, read-only. Team radio is not included (F1 decreased radio coverage in 2026).
Tools
Discovery
Tool | Use |
| Find Grand Prix weekends → |
| Find practice / qualifying / sprint / race → |
| Map driver numbers to names and teams |
Data (one tool for each endpoint)
get_session_result, get_starting_grid, get_laps, get_stints, get_pit, get_position, get_intervals, get_overtakes, get_race_control, get_weather, get_championship_drivers, get_championship_teams, get_car_data, get_location.
Composite
Tool | Result |
| Classification with names, teams, grid, positions gained, status (DNF/DNS/DSQ) |
| Compound sequence, stint lengths and pit stops for each driver |
| Fastest lap, sectors, speeds, theoretical best lap and delta for 2–10 drivers |
All tools accept "latest" for session_key / meeting_key.
Common arguments
Typed parameters – equality filters such as
session_key,driver_number(one number or a list),lap_number.filters– comparison filters:[{"field":"lap_duration","op":"<","value":90}]. The server checks the field names.date_from/date_to– time range (UTC, ISO 8601) for endpoints with adateattribute.fields– return only these attributes.limit– maximum records (default 200, max 1000).
Size control
Large results do not go to the model in full:
Results above
limitare sampled evenly for time series (or cut for other data) and get a summary (min / max / avg of numeric fields and first / last date) computed on all records.get_car_dataandget_location(~3.7 Hz) needsession_key, onedriver_number, and alap_numberor a date range of 10 minutes or less. Withlap_number, the server finds the start and end of the lap for you.
Reliability
Cache: 6 h for historical data, 10 min for the calendar, 10 s for
latestqueries.Requests are spaced (350 ms) and retried on HTTP 429 / 5xx.
"No results found" (HTTP 404) is returned as an empty list with a hint.
Errors go back to the model as
isErrorresults with a clear message.
Related MCP server: OpenF1 MCP Server
Install
Node.js 20 or later.
npm install
npm run build
npm test # unit + MCP protocol tests (no network)
npm run smoke # tests against the real OpenF1 APIClaude Code
claude mcp add openf1 -- node /absolute/path/openf1-mcp/dist/index.jsClaude Desktop
claude_desktop_config.json:
{
"mcpServers": {
"openf1": {
"command": "node",
"args": ["/absolute/path/openf1-mcp/dist/index.js"]
}
}
}MCP Inspector
npm run inspectConfiguration
Variable | Default | Description |
| – | Bearer token for the paid real-time tier. Historical data needs no token. |
|
| API base URL. |
|
| Minimum time between requests. |
|
| Default record limit. |
Example prompts
"Who won the 2025 São Paulo GP and how many positions did each driver gain?"
"Compare the tyre strategies of Norris and Piastri in the last race."
"Show the speed and throttle of Verstappen on lap 10 of the latest race."
"Were there safety cars in the 2025 Brazil race? On which laps?"
Project structure
src/
index.ts stdio entry point, server instructions, env config
endpoints.ts endpoint catalog (parameters, attributes, guards)
client.ts HTTP client: query builder, cache, throttle, retry
shape.ts projection, limit, sampling, numeric summary
tools.ts tool registration, telemetry guards, composite tools
test/ vitest suite with a fake API
scripts/smoke.ts real API checkNotes
OpenF1 is an unofficial project and is not associated with the Formula 1 companies. F1 and related marks are trademarks of Formula One Licensing B.V.
Available Tools
20 toolscompare_fastest_lapsCompare fastest lapsARead-onlyIdempotent
Compare the fastest lap of 2 to 10 drivers in a session: lap time, sectors, speeds, best sectors, theoretical best lap and delta to the fastest driver.
| Name | Required | Description | Default |
|---|---|---|---|
| session_key | Yes | Session identifier or "latest". | |
| driver_number | Yes | Driver numbers to compare. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that by enumerating the computed outputs (theoretical best lap, delta to fastest), which matters because no output schema exists. It stops short of disclosing edge cases such as drivers with no valid lap time.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with the scope and the returned metrics front-loaded and no filler. Every clause (driver count, session, output fields) carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description usefully enumerates what comes back, which is the main completeness need here. It is nearly complete for a simple two-parameter read tool, missing only behavior for invalid or missing lap data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and both parameters are documented there, including the 2–10 item bounds. The description's '2 to 10 drivers in a session' restates the schema constraints rather than adding meaning, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb ('Compare') plus resource ('fastest lap') and an explicit enumeration of the compared metrics (lap time, sectors, speeds, best sectors, theoretical best lap, delta). An agent can tell this is an analytical comparison tool rather than a raw data fetch like get_laps, 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by 'in a session' and the 2-to-10 driver range, which tells the agent this is for multi-driver head-to-head analysis. However, there is no explicit statement of when to prefer this over get_laps, get_session_result, or get_tyre_strategy, and no prerequisite/error guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_car_dataCar telemetryARead-onlyIdempotent
Car telemetry at about 3.7 Hz: speed, RPM, gear, throttle, brake, DRS. VERY large data: you must give session_key, ONE driver_number and a lap_number or a date range (max 10 minutes).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of records to return (default 200, max 1000). A summary is added when the result is larger. | |
| fields | No | Return only these attributes. Use this to make large results smaller. | |
| date_to | No | End of the time range (UTC, ISO 8601). Filters on "date" <= value. | |
| filters | No | Extra comparison filters, e.g. [{"field":"lap_duration","op":"<","value":90}]. Allowed fields: brake, date, driver_number, drs, meeting_key, n_gear, rpm, session_key, speed, throttle. Array fields cannot be filtered. | |
| date_from | No | Start of the time range (UTC, ISO 8601), e.g. "2025-11-09T17:05:00Z". Filters on "date" >= value. | |
| lap_number | No | Lap number. The server finds the start and end time of this lap and returns only its telemetry. | |
| session_key | No | Session identifier. Use "latest" for the current or most recent session. | |
| driver_number | No | Driver number(s) for the season, e.g. 1, 44, 81. Give a list to get more than one driver. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safe-read profile, and the description usefully adds the volume warning ('VERY large data'), the ~3.7 Hz resolution and the mandatory scoping. However, the instruction 'ONE driver_number' directly conflicts with the schema, which accepts an integer array of up to 30 drivers, so the guidance could cause an agent to reject valid multi-driver calls.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tightly written sentences, front-loaded with what the data is and followed immediately by the volume warning and the required scoping. No filler whatsoever.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, resolution, volume and mandatory filters for an eight-parameter, read-only tool with a fully documented schema and no output schema. The one gap is the incorrect singular driver constraint, which is the main thing an agent could get wrong.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the description goes beyond it by imposing the lap_number-or-date-range exclusivity and the 10-minute window, neither of which appears in the schema. The driver_number restriction it adds is, however, wrong relative to the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource (car telemetry) plus the exact signals returned (speed, RPM, gear, throttle, brake, DRS) and the sampling rate, which cleanly separates it from siblings like get_laps, get_location and get_intervals. An agent can pick this tool 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete prerequisites ('you must give session_key, ONE driver_number and a lap_number or a date range') and an explicit bound (max 10 minutes), which is real when-to-use guidance. It stops short of naming alternatives (e.g. get_laps for aggregated lap data) or stating when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_championship_driversDrivers championship (beta)ARead-onlyIdempotent
Drivers championship points and position before and after a race. Race sessions only.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of records to return (default 200, max 1000). A summary is added when the result is larger. | |
| fields | No | Return only these attributes. Use this to make large results smaller. | |
| filters | No | Extra comparison filters, e.g. [{"field":"lap_duration","op":"<","value":90}]. Allowed fields: driver_number, meeting_key, points_current, points_start, position_current, position_start, session_key. Array fields cannot be filtered. | |
| meeting_key | No | Meeting (Grand Prix weekend) identifier. Use "latest" for the current or most recent meeting. | |
| session_key | No | Session identifier. Use "latest" for the current or most recent session. | |
| driver_number | No | Driver number(s) for the season, e.g. 1, 44, 81. Give a list to get more than one driver. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this as a safe, idempotent, read-only operation. The description adds the race-session-only constraint and clarifies that values are shown before and after a race, but it does not explain pagination, beta behavior, or output structure beyond the basic resource.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with the core purpose front-loaded and no wasted text. The session-type restriction is stated directly after the main description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With full schema coverage, read-only annotations, and no output schema, the description adequately covers what the tool returns and its key constraint. It stops short of explaining return shape or beta caveats, but nothing critical for invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all six parameters are fully documented in the input schema. The description adds no parameter-specific information beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the resource (drivers championship points and positions) and the temporal scope (before and after a race). It does not explicitly contrast itself with sibling tools such as get_championship_teams, though the 'Drivers' qualifier implicitly distinguishes it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Race sessions only' gives a useful usage constraint, excluding non-race sessions. However, it does not name alternatives or specify when to prefer this tool over related ones like get_session_result or get_championship_teams.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_championship_teamsTeams championship (beta)ARead-onlyIdempotent
Teams championship points and position before and after a race. Race sessions only.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of records to return (default 200, max 1000). A summary is added when the result is larger. | |
| fields | No | Return only these attributes. Use this to make large results smaller. | |
| filters | No | Extra comparison filters, e.g. [{"field":"lap_duration","op":"<","value":90}]. Allowed fields: meeting_key, points_current, points_start, position_current, position_start, session_key, team_name. Array fields cannot be filtered. | |
| team_name | No | Team name, e.g. "McLaren". | |
| meeting_key | No | Meeting (Grand Prix weekend) identifier. Use "latest" for the current or most recent meeting. | |
| session_key | No | Session identifier. Use "latest" for the current or most recent session. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, non-destructive and openWorld, so the safety profile is covered. The description adds the race-sessions-only restriction, but says nothing about result scope (per-team rows for one session?) or the summary behaviour on large results, which the schema only hints at.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero waste, with the scope statement front-loaded and the constraint immediately after. Nothing to trim and nothing buried.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a six-optional-parameter read tool with no output schema, the definition is thin: it does not clarify the granularity of returned rows or that points_start/position_start vs _current correspond to 'before and after'. Annotations carry the safety story, but the description leaves the data shape under-explained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so limit, fields, filters, team_name, meeting_key and session_key are already fully documented. The description adds no param-level meaning beyond reinforcing that session_key should point at a race session; baseline 3 applies where the schema does the work.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names the resource precisely (teams championship points and position) and its temporal scope ('before and after a race'), which also implicitly separates it from get_championship_drivers. It is a noun phrase rather than a verb+resource ('get/list'), but an agent can tell what it retrieves.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Race sessions only' is a real usage constraint that excludes sprint/qualifying/practice sessions, which is valuable guidance. However, it never names the sibling alternative (get_championship_drivers) or states the condition that would route an agent there instead, so usage 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_driversDriversBRead-onlyIdempotent
Driver details for a session: name, acronym, team, team colour, headshot URL.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of records to return (default 200, max 1000). A summary is added when the result is larger. | |
| fields | No | Return only these attributes. Use this to make large results smaller. | |
| filters | No | Extra comparison filters, e.g. [{"field":"lap_duration","op":"<","value":90}]. Allowed fields: broadcast_name, country_code, driver_number, first_name, full_name, headshot_url, last_name, meeting_key, name_acronym, session_key, team_colour, team_name. Array fields cannot be filtered. | |
| team_name | No | Team name, e.g. "McLaren". | |
| meeting_key | No | Meeting (Grand Prix weekend) identifier. Use "latest" for the current or most recent meeting. | |
| session_key | No | Session identifier. Use "latest" for the current or most recent session. | |
| name_acronym | No | Three-letter acronym, e.g. "VER", "HAM". | |
| driver_number | No | Driver number(s) for the season, e.g. 1, 44, 81. Give a list to get more than one driver. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the useful fact that results are session-scoped and enumerates the returned fields (valuable since there is no output schema). It says nothing about default record counts, result-size behavior, or error/permission conditions that the schema only partly hints at.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with zero filler; the returned-field list is the most useful information and comes first. It is arguably slightly underspecified rather than verbose, but there is no wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With eight parameters, no output schema, and full schema coverage, the description does enough to identify the payload fields but not enough to guide scoping decisions (session vs meeting vs season-wide driver_number lookups) or result-size handling. Safety is carried by annotations, so the remaining gap is modest but real.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every parameter including limit, filters, and the 'latest' sentinel for session_key/meeting_key is fully documented in the schema. The description's field list loosely corresponds to the queryable attributes but adds no filtering syntax or scoping semantics beyond what the schema already provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the specific resource (driver details) and enumerates the returned attributes (name, acronym, team, team colour, headshot URL), which is concrete and unambiguous. It does not distinguish this tool from the closest sibling, get_championship_drivers, so an agent must infer that this one returns per-session driver metadata rather than standings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to call this versus get_championship_drivers, get_session_result, or get_starting_grid. The phrase 'for a session' weakly implies a session-scoped lookup, but no prerequisites, alternatives, or exclusions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_intervalsIntervalsBRead-onlyIdempotent
Gap to the car ahead and gap to the leader during a race (about every 4 s). Large data: filter by driver and time.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of records to return (default 200, max 1000). A summary is added when the result is larger. | |
| fields | No | Return only these attributes. Use this to make large results smaller. | |
| date_to | No | End of the time range (UTC, ISO 8601). Filters on "date" <= value. | |
| filters | No | Extra comparison filters, e.g. [{"field":"lap_duration","op":"<","value":90}]. Allowed fields: date, driver_number, gap_to_leader, interval, meeting_key, session_key. Array fields cannot be filtered. | |
| date_from | No | Start of the time range (UTC, ISO 8601), e.g. "2025-11-09T17:05:00Z". Filters on "date" >= value. | |
| meeting_key | No | Meeting (Grand Prix weekend) identifier. Use "latest" for the current or most recent meeting. | |
| session_key | No | Session identifier. Use "latest" for the current or most recent session. | |
| driver_number | No | Driver number(s) for the season, e.g. 1, 44, 81. Give a list to get more than one driver. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely new context—sampling interval of roughly 4 seconds and the warning that the dataset is large—but says nothing about default result size behavior, summaries, or ordering.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler, and the high-value information (what the data is, how often it is sampled) is front-loaded. The telegraphic "Large data: filter by driver and time" phrasing is slightly clipped but still earns its place as an efficiency warning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 8 optional parameters and no output schema, the description could do more: it never names the returned attributes (interval, gap_to_leader), never states that a session or meeting scope is effectively needed, and never explains the summary behavior that the limit parameter references. The fully documented schema compensates partially, making this adequate but with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every parameter (limit, fields, date_from/date_to, filters, meeting_key, session_key, driver_number) is already documented in the schema. The description's "filter by driver and time" only echoes driver_number and the date range, adding no syntax or semantics beyond the schema. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States the specific resource (gap to car ahead and gap to leader) plus the sampling cadence (~every 4 s) and the context (during a race), so an agent knows exactly what data comes back. It does not explicitly contrast with siblings like get_position or get_laps, which is the only thing keeping it from a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Large data: filter by driver and time" implies how to call it efficiently, but there is no explicit when-to-use / when-not-to-use statement and no named alternative (e.g. get_position for raw classification). Usage is implied rather than spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_lapsLapsBRead-onlyIdempotent
Lap data: lap time, sector times, intermediate and speed-trap speeds, pit-out flag, mini-sector segments (segments are not available in races).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of records to return (default 200, max 1000). A summary is added when the result is larger. | |
| fields | No | Return only these attributes. Use this to make large results smaller. | |
| filters | No | Extra comparison filters, e.g. [{"field":"lap_duration","op":"<","value":90}]. Allowed fields: date_start, driver_number, duration_sector_1, duration_sector_2, duration_sector_3, i1_speed, i2_speed, is_pit_out_lap, lap_duration, lap_number, meeting_key, segments_sector_1, segments_sector_2, segments_sector_3, session_key, st_speed. Array fields cannot be filtered. | |
| lap_number | No | Lap number (starts at 1). | |
| meeting_key | No | Meeting (Grand Prix weekend) identifier. Use "latest" for the current or most recent meeting. | |
| session_key | No | Session identifier. Use "latest" for the current or most recent session. | |
| driver_number | No | Driver number(s) for the season, e.g. 1, 44, 81. Give a list to get more than one driver. | |
| is_pit_out_lap | No | Only pit-out laps (true) or only other laps (false). |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds a useful behavioral caveat that segments are not available in races, but it does not discuss pagination, filtering behavior, or result-size handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense sentence that front-loads the returned data fields and includes the race-availability caveat. It is concise and wastes little space, though the list-like structure could be clearer.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an eight-parameter read-only endpoint with no output schema, the description covers the returned data and one important availability caveat. However, it omits usage context and does not help the agent decide how to scope requests via session, meeting, driver, or filters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all eight parameters are already documented in the schema, including limit, filters, meeting_key, session_key, and driver_number. The description adds no parameter-specific meaning beyond the schema, making the baseline 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the resource and returned fields: lap time, sector times, intermediate/speed-trap speeds, pit-out flag, and mini-sector segments. It is more specific than a tautology, but it does not distinguish the tool from siblings such as get_stints or compare_fastest_laps.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use get_laps versus alternatives. The data fields imply it is the lap-level endpoint, but the description gives no exclusions, prerequisites, or alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_locationCar locationARead-onlyIdempotent
Approximate car position on track (x, y, z) at about 3.7 Hz. VERY large data: you must give session_key, ONE driver_number and a lap_number or a date range (max 10 minutes).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of records to return (default 200, max 1000). A summary is added when the result is larger. | |
| fields | No | Return only these attributes. Use this to make large results smaller. | |
| date_to | No | End of the time range (UTC, ISO 8601). Filters on "date" <= value. | |
| filters | No | Extra comparison filters, e.g. [{"field":"lap_duration","op":"<","value":90}]. Allowed fields: date, driver_number, meeting_key, session_key, x, y, z. Array fields cannot be filtered. | |
| date_from | No | Start of the time range (UTC, ISO 8601), e.g. "2025-11-09T17:05:00Z". Filters on "date" >= value. | |
| lap_number | No | Lap number. The server finds the start and end time of this lap and returns only its telemetry. | |
| session_key | No | Session identifier. Use "latest" for the current or most recent session. | |
| driver_number | No | Driver number(s) for the season, e.g. 1, 44, 81. Give a list to get more than one driver. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, so the description's added value is the sampling rate (~3.7 Hz) and the 'VERY large data' warning plus the 10-minute range cap, which genuinely shapes invocation strategy. It doesn't describe accuracy or response shape, so not a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences, front-loaded with the resource and sample rate, then the invocation constraints. No filler; every clause carries actionable information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, and the description covers volume, frequency, and required scoping well enough to call the tool safely. It leaves out what fields come back beyond x/y/z and any accuracy caveat, which would round out completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the description reinforces the session_key/lap_number/date-range usage model and adds the 10-minute cap that the schema doesn't state. However, 'ONE driver_number' conflicts with the schema's allowed integer array (maxItems 30), creating ambiguity rather than adding meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource (car position on track) and even the payload shape (x, y, z) and sampling rate (3.7 Hz), which goes well beyond the title 'Car location'. It does not explicitly name how it differs from siblings like get_position or get_car_data, which prevents a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete preconditions: session_key, exactly one driver_number, and either lap_number or a date range capped at 10 minutes, framed by a data-volume warning. What's missing is an explicit statement of when to prefer this over get_car_data or get_position.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_meetingsMeetings (Grand Prix weekends)ARead-onlyIdempotent
Find meetings (Grand Prix or testing weekends). Use this first to get a meeting_key. Data starts in 2023.
| Name | Required | Description | Default |
|---|---|---|---|
| year | No | Season year, e.g. 2025. | |
| limit | No | Maximum number of records to return (default 200, max 1000). A summary is added when the result is larger. | |
| fields | No | Return only these attributes. Use this to make large results smaller. | |
| filters | No | Extra comparison filters, e.g. [{"field":"lap_duration","op":"<","value":90}]. Allowed fields: circuit_key, circuit_info_url, circuit_image, circuit_short_name, circuit_type, country_code, country_flag, country_key, country_name, date_end, date_start, gmt_offset, is_cancelled, location, meeting_key, meeting_name, meeting_official_name, year. Array fields cannot be filtered. | |
| location | No | City or location, e.g. "São Paulo", "Monza". | |
| meeting_key | No | Meeting (Grand Prix weekend) identifier. Use "latest" for the current or most recent meeting. | |
| country_name | No | Country name in English, e.g. "Brazil", "Singapore". | |
| circuit_short_name | No | Circuit short name, e.g. "Interlagos". |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely non-obvious context: the corpus starts in 2023 and the tool is the gateway for meeting_key, which is the key behavioral fact an agent needs. Return shape and result-size behavior are left to 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, zero filler, with the core purpose and the workflow directive front-loaded. Every clause (weekend types, meeting_key, 2023 cutoff) carries information an agent would otherwise have to discover by trial.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description could ideally say what a meeting record contains (meeting_key, name, date_start/end, circuit, country) since those are the fields an agent will pass downstream. Still, it covers the essential discovery role, the data horizon, and the optional-parameter nature is clear from the schema's zero required params.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% across all 8 parameters, including filterable fields, limit semantics and the "latest" enum for meeting_key, so the schema carries the parameter burden. The description adds nothing beyond the implicit point that this is where a meeting_key comes from, which is baseline-3 territory.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Find meetings") and narrows scope to Grand Prix or testing weekends, which distinguishes it from the session/lap/telemetry siblings. It stops short of naming the nearest sibling (get_sessions) as an alternative, so differentiation is implied by workflow rather than explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Use this first to get a meeting_key" gives a clear entry-point ordering that tells an agent when to reach for this tool versus the downstream data tools. It lacks any when-not condition (e.g., when you already have a meeting_key, skip this), so it falls short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_overtakesOvertakesARead-onlyIdempotent
Position exchanges between two drivers in a race (on track, pit stops or penalties). Data can be incomplete.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of records to return (default 200, max 1000). A summary is added when the result is larger. | |
| fields | No | Return only these attributes. Use this to make large results smaller. | |
| date_to | No | End of the time range (UTC, ISO 8601). Filters on "date" <= value. | |
| filters | No | Extra comparison filters, e.g. [{"field":"lap_duration","op":"<","value":90}]. Allowed fields: date, meeting_key, overtaken_driver_number, overtaking_driver_number, position, session_key. Array fields cannot be filtered. | |
| position | No | Position of the overtaking driver after the overtake. | |
| date_from | No | Start of the time range (UTC, ISO 8601), e.g. "2025-11-09T17:05:00Z". Filters on "date" >= value. | |
| meeting_key | No | Meeting (Grand Prix weekend) identifier. Use "latest" for the current or most recent meeting. | |
| session_key | No | Session identifier. Use "latest" for the current or most recent session. | |
| overtaken_driver_number | No | Driver who was overtaken. | |
| overtaking_driver_number | No | Driver who made the overtake. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this as a safe, read-only, idempotent operation. The description adds meaningful behavioral context by warning that data can be incomplete and by clarifying which race events count as overtakes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded and compact: one sentence defines the resource and the second sentence adds a critical data-quality caveat. There is no wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate given rich annotations and complete schema parameter coverage, but it is sparse for a ten-parameter query tool. It does not explain return shape or recommend scoping by meeting/session/date, though the schema partially compensates.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all ten parameters are already well documented in the schema. The description adds no parameter-specific meaning beyond that, which matches the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource as position exchanges between two drivers, including on-track, pit-stop, and penalty cases. It is more specific than the tool name alone, but it does not explicitly distinguish itself from nearby siblings such as get_position or get_intervals.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool versus alternatives like get_position, get_intervals, or get_laps. The phrase 'in a race' implies scoping, but no when/when-not conditions or recommended filters are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_pitPit laneBRead-onlyIdempotent
Pit lane passages: lap, time in pit lane (lane_duration) and stationary stop time (stop_duration, from the 2024 US GP onwards).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of records to return (default 200, max 1000). A summary is added when the result is larger. | |
| fields | No | Return only these attributes. Use this to make large results smaller. | |
| date_to | No | End of the time range (UTC, ISO 8601). Filters on "date" <= value. | |
| filters | No | Extra comparison filters, e.g. [{"field":"lap_duration","op":"<","value":90}]. Allowed fields: date, driver_number, lane_duration, lap_number, meeting_key, pit_duration, session_key, stop_duration. Array fields cannot be filtered. | |
| date_from | No | Start of the time range (UTC, ISO 8601), e.g. "2025-11-09T17:05:00Z". Filters on "date" >= value. | |
| lap_number | No | Lap number (starts at 1). | |
| meeting_key | No | Meeting (Grand Prix weekend) identifier. Use "latest" for the current or most recent meeting. | |
| session_key | No | Session identifier. Use "latest" for the current or most recent session. | |
| driver_number | No | Driver number(s) for the season, e.g. 1, 44, 81. Give a list to get more than one driver. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, and open-world behavior, so the safety profile is covered. The description adds useful context by distinguishing lane_duration from stationary stop_duration and noting stop_duration availability from the 2024 US GP onwards, but it does not discuss pagination or full return behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no wasted wording. It states the resource, the key returned measurements, and the important stop_duration availability caveat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The input schema is fully documented and annotations carry the safety profile, so the description mainly needs to identify the resource and return content. It lists the core pit lane fields and the stop_duration caveat, though it does not fully explain every returned attribute or provide sibling-routing guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all nine parameters are already documented in the input schema. The description names lane_duration and stop_duration and their availability, which helps interpret filterable fields, but it adds no top-level parameter syntax or usage beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the specific resource (pit lane passages) and key measurements (lap, lane_duration, stop_duration), which clearly distinguishes it from general lap and stint endpoints. It does not explicitly frame the operation as retrieval or name a sibling alternative, keeping it 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to choose this tool over get_laps, get_stints, or other siblings, nor any stated prerequisites. The only contextual note is that stop_duration is available from the 2024 US GP onwards, which is a data-availability caveat rather than tool-selection guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_positionPosition changesBRead-onlyIdempotent
Driver position during a session: the initial position and each change.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of records to return (default 200, max 1000). A summary is added when the result is larger. | |
| fields | No | Return only these attributes. Use this to make large results smaller. | |
| date_to | No | End of the time range (UTC, ISO 8601). Filters on "date" <= value. | |
| filters | No | Extra comparison filters, e.g. [{"field":"lap_duration","op":"<","value":90}]. Allowed fields: date, driver_number, meeting_key, position, session_key. Array fields cannot be filtered. | |
| position | No | Position. | |
| date_from | No | Start of the time range (UTC, ISO 8601), e.g. "2025-11-09T17:05:00Z". Filters on "date" >= value. | |
| meeting_key | No | Meeting (Grand Prix weekend) identifier. Use "latest" for the current or most recent meeting. | |
| session_key | No | Session identifier. Use "latest" for the current or most recent session. | |
| driver_number | No | Driver number(s) for the season, e.g. 1, 44, 81. Give a list to get more than one driver. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this a safe, idempotent read (readOnlyHint, idempotentHint, destructiveHint=false), so the description needn't restate safety. It adds useful data semantics (initial position and each subsequent change), but says nothing about ordering, sampling granularity, or how large result sets are truncated beyond what the schema's limit parameter implies.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with zero filler. Every word contributes to the purpose statement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should clarify what a record looks like (driver_number, position, timestamp ordering) and how it relates to interval/overtake data. Annotations and full schema coverage make it callable, but an agent must infer the result shape and the distinction from sibling position-related tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% across all 9 parameters, including 'latest' semantics for session_key/meeting_key and the filter allowed-fields list, so the schema carries the parameter burden. The description contributes no additional parameter guidance beyond the schema, which is the baseline-3 case.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource (driver position) and scope (initial position plus each change during a session), so the agent knows exactly what data comes back. It does not distinguish itself from adjacent siblings like get_intervals, get_overtakes, or get_starting_grid, which also concern track order.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no indication of when to reach for this tool versus get_intervals, get_overtakes, or get_starting_grid, and no prerequisites are mentioned. The phrase 'during a session' weakly implies a session_key is needed, but nothing explicit routes the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_race_controlRace controlBRead-onlyIdempotent
Race control messages: flags, safety car, DRS, penalties, track limits, session status.
| Name | Required | Description | Default |
|---|---|---|---|
| flag | No | "GREEN", "YELLOW", "DOUBLE YELLOW", "RED", "BLUE", "CHEQUERED", "BLACK AND WHITE", "CLEAR". | |
| limit | No | Maximum number of records to return (default 200, max 1000). A summary is added when the result is larger. | |
| scope | No | "Track", "Driver", "Sector". | |
| fields | No | Return only these attributes. Use this to make large results smaller. | |
| date_to | No | End of the time range (UTC, ISO 8601). Filters on "date" <= value. | |
| filters | No | Extra comparison filters, e.g. [{"field":"lap_duration","op":"<","value":90}]. Allowed fields: category, date, driver_number, flag, lap_number, meeting_key, message, qualifying_phase, scope, sector, session_key. Array fields cannot be filtered. | |
| category | No | "Flag", "SafetyCar", "Drs", "CarEvent", "SessionStatus", "Other". | |
| date_from | No | Start of the time range (UTC, ISO 8601), e.g. "2025-11-09T17:05:00Z". Filters on "date" >= value. | |
| lap_number | No | Lap number (starts at 1). | |
| meeting_key | No | Meeting (Grand Prix weekend) identifier. Use "latest" for the current or most recent meeting. | |
| session_key | No | Session identifier. Use "latest" for the current or most recent session. | |
| driver_number | No | Driver number(s) for the season, e.g. 1, 44, 81. Give a list to get more than one driver. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true. The description adds only content categories, not behavioral context such as ordering, pagination behavior, default result sizes, or how filtering affects results. It adds little beyond the safety profile already provided by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with zero waste. It states the resource and its content categories immediately, with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 12 optional parameters and no output schema, the description is minimal but the schema is fully documented. It does not mention that the tool supports filtering by driver, session, meeting, date range, lap number, or custom filters, so an agent relying only on the description would miss major capabilities, though the schema compensates.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 12 parameters thoroughly, including enums for flag, scope, and category. The description contributes no additional parameter meaning, which is acceptable at the baseline given complete schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource as race control messages and enumerates the kinds of content returned (flags, safety car, DRS, penalties, track limits, session status). It lacks an explicit verb and does not differentiate from siblings, but the resource is unambiguous and unlike any sibling tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the content list: an agent can infer this tool is for race control messages. However, there is no explicit when-to-use guidance, no prerequisites, and no named alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_race_summaryRace summaryARead-onlyIdempotent
Classification of a session with driver names, teams, grid position, positions gained, laps, gap and status (DNF/DNS/DSQ). Works for races, sprints, qualifying and practice.
| Name | Required | Description | Default |
|---|---|---|---|
| session_key | Yes | Session identifier or "latest". |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds the returned field list, which is valuable given there is no output schema, but says nothing about ordering, the behavior of 'latest' for non-race sessions, or error cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences, front-loaded with the returned payload and followed by the applicable session types. Nothing is repeated or padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the enumerated fields effectively serve as the return contract, and the session-type coverage is stated. The main omission is how it differs from get_session_result and whether results are ordered by finishing position.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
One parameter with 100% schema description coverage; the schema already documents session_key and the 'latest' constant. The description adds no format hints or examples 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.
Does the description clearly state what the tool does and how it differs from similar tools?
Names the resource (session classification / race summary) and enumerates the exact fields returned, so the agent knows precisely what it gets. It does not differentiate itself from the near-identical sibling get_session_result, which leaves a real ambiguity unresolved.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Works for races, sprints, qualifying and practice' is useful scope guidance for which session types are valid. But there is no exclusion or routing guidance against get_session_result, get_position or get_intervals, so the agent must infer when this tool is preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_session_resultSession resultARead-onlyIdempotent
Final standings of a session (position, laps, duration, gap, DNF/DNS/DSQ). In qualifying, duration and gap_to_leader are arrays for Q1, Q2, Q3.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of records to return (default 200, max 1000). A summary is added when the result is larger. | |
| fields | No | Return only these attributes. Use this to make large results smaller. | |
| filters | No | Extra comparison filters, e.g. [{"field":"lap_duration","op":"<","value":90}]. Allowed fields: dnf, dns, dsq, driver_number, duration, gap_to_leader, number_of_laps, meeting_key, position, session_key. Array fields cannot be filtered. | |
| position | No | Final position. | |
| meeting_key | No | Meeting (Grand Prix weekend) identifier. Use "latest" for the current or most recent meeting. | |
| session_key | No | Session identifier. Use "latest" for the current or most recent session. | |
| driver_number | No | Driver number(s) for the season, e.g. 1, 44, 81. Give a list to get more than one driver. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: the DNF/DNS/DSQ flags and the special array behavior for duration and gap_to_leader in qualifying.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences, front-loaded with the core result definition and followed by a useful edge case. Every sentence earns its place with no redundant restatement of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given seven optional parameters with full schema coverage and no output schema, the description is nearly complete: it names the returned fields and explains the qualifying array nuance. A minor gap is the absence of any note about pagination or the limit-summary behavior, though the schema covers the limit parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all seven parameters are fully documented in the schema. The description adds no parameter-specific semantics beyond what the schema already provides, which is the expected baseline when schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource and scope: 'Final standings of a session' with enumerated fields (position, laps, duration, gap, DNF/DNS/DSQ). This distinguishes it from live-position tools like get_position, but it does not explicitly name or contrast with any sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by 'Final standings of a session' and the qualifying-array note, but there is no explicit when-to-use/when-not guidance or reference to alternatives such as get_position or get_race_summary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_sessionsSessionsARead-onlyIdempotent
Find sessions (practice, qualifying, sprint, race). Use this to get a session_key, which most other tools need.
| Name | Required | Description | Default |
|---|---|---|---|
| year | No | Season year, e.g. 2025. | |
| limit | No | Maximum number of records to return (default 200, max 1000). A summary is added when the result is larger. | |
| fields | No | Return only these attributes. Use this to make large results smaller. | |
| filters | No | Extra comparison filters, e.g. [{"field":"lap_duration","op":"<","value":90}]. Allowed fields: circuit_key, circuit_short_name, country_code, country_key, country_name, date_end, date_start, gmt_offset, is_cancelled, location, meeting_key, session_key, session_name, session_type, year. Array fields cannot be filtered. | |
| location | No | City or location, e.g. "São Paulo". | |
| meeting_key | No | Meeting (Grand Prix weekend) identifier. Use "latest" for the current or most recent meeting. | |
| session_key | No | Session identifier. Use "latest" for the current or most recent session. | |
| country_name | No | Country name in English, e.g. "Brazil". | |
| session_name | No | Session name: "Practice 1", "Practice 2", "Practice 3", "Qualifying", "Sprint Qualifying", "Sprint", "Race". | |
| session_type | No | Session type: "Practice", "Qualifying", "Race". |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so safety and repeatability are covered structurally. The description adds the useful workflow fact that this tool yields the session_key other tools consume, but says nothing about result volume, default limits, or what happens with no filters applied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero waste, with the capability statement first and the motivating reason for calling it second. Nothing could be removed without losing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-required-parameter discovery tool with a fully documented schema and no output schema, the description covers what the agent needs to decide to call it and why. It could note that an unfiltered call returns many sessions and that narrowing by year/meeting_key is advisable, but nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% across all 10 parameters, including the 'latest' sentinel values, filter field allowlist and limit behavior, so the schema does the heavy lifting. The description only loosely gestures at session types without adding syntax, defaults, or combination guidance beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Find sessions') and enumerates the session types returned, so an agent knows this is the session-level discovery endpoint rather than the meeting-level one. It does not explicitly name get_meetings as the alternative, so sibling differentiation is implied by the domain vocabulary 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Use this to get a session_key, which most other tools need' is a concrete usage directive that tells the agent exactly why and when to call this before downstream tools. There is no explicit when-not guidance or named alternative for cases where the agent already has a session_key.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_starting_gridStarting gridBRead-onlyIdempotent
Starting grid of a race, with the qualifying lap time of each driver.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of records to return (default 200, max 1000). A summary is added when the result is larger. | |
| fields | No | Return only these attributes. Use this to make large results smaller. | |
| filters | No | Extra comparison filters, e.g. [{"field":"lap_duration","op":"<","value":90}]. Allowed fields: driver_number, lap_duration, meeting_key, position, session_key. Array fields cannot be filtered. | |
| position | No | Grid position. | |
| meeting_key | No | Meeting (Grand Prix weekend) identifier. Use "latest" for the current or most recent meeting. | |
| session_key | No | Session identifier. Use "latest" for the current or most recent session. | |
| driver_number | No | Driver number(s) for the season, e.g. 1, 44, 81. Give a list to get more than one driver. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive behavior, so the description is not carrying the safety burden. It adds useful content context (one row per driver with quali lap time) but says nothing about ordering, whether a summary is appended for large results, or how unfiltered calls behave.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler; the key resource and its distinguishing payload come first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 7 optional parameters and no output schema, the description should say which session's grid is returned (presumably the race session) and what happens when no meeting/session is supplied. It leaves the agent to infer scoping entirely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so limit, fields, filters, position, meeting_key, session_key and driver_number are all documented in the schema, including the 'latest' convention. The description adds no parameter meaning beyond that, which is the baseline for fully-covered schemas.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific resource ('starting grid of a race') and adds the distinguishing payload ('qualifying lap time of each driver'), so an agent knows it returns grid order plus quali times rather than race results. It does not explicitly contrast with the nearest sibling, get_session_result, but the resource itself is distinctive.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to pick this over get_session_result or get_laps, nor any note that the grid belongs to a race session and should be scoped by session_key/meeting_key. The agent must infer selection criteria entirely from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_stintsStintsCRead-onlyIdempotent
Tyre stints: compound, first and last lap, tyre age at the start of the stint.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of records to return (default 200, max 1000). A summary is added when the result is larger. | |
| fields | No | Return only these attributes. Use this to make large results smaller. | |
| filters | No | Extra comparison filters, e.g. [{"field":"lap_duration","op":"<","value":90}]. Allowed fields: compound, driver_number, lap_end, lap_start, meeting_key, session_key, stint_number, tyre_age_at_start. Array fields cannot be filtered. | |
| compound | No | "SOFT", "MEDIUM", "HARD", "INTERMEDIATE", "WET". | |
| meeting_key | No | Meeting (Grand Prix weekend) identifier. Use "latest" for the current or most recent meeting. | |
| session_key | No | Session identifier. Use "latest" for the current or most recent session. | |
| stint_number | No | Stint number (starts at 1). | |
| driver_number | No | Driver number(s) for the season, e.g. 1, 44, 81. Give a list to get more than one driver. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds no behavioral context of its own — nothing about result ordering, granularity (one row per stint), or how 'latest' resolution behaves — so it does not exploit the room annotations leave.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is short and front-loaded with zero padding, which is good, but it is a sentence fragment that omits the action verb, so brevity here comes at the cost of a well-formed statement of what the call does.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 8 optional parameters, no output schema, and no required keys, the description should explain what a stint record is and how to scope a query. It lists four attributes but says nothing about the query surface, result shape, or default behavior, leaving the agent under-informed for a moderately complex endpoint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every parameter (including the compound enum values and filterable field list) is already documented in the schema. The description mentions compound and tyre age only as returned fields, adding no parameter-level meaning beyond that; baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the resource and enumerates the returned attributes (compound, first/last lap, tyre age at start), which is more informative than the bare name 'get_stints'. But it is a noun-phrase fragment with no verb and no scope statement, so an agent cannot distinguish it from the sibling get_tyre_strategy, which plausibly returns overlapping data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to call this instead of get_laps, get_pit, or get_tyre_strategy, and no mention of the prerequisites implied by the session_key/meeting_key parameters. The agent must infer usage entirely from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_tyre_strategyTyre strategyBRead-onlyIdempotent
Tyre strategy for each driver in a session: compound sequence, stint lengths and pit stops.
| Name | Required | Description | Default |
|---|---|---|---|
| session_key | Yes | Session identifier or "latest". | |
| driver_number | No | Optional driver number(s). Omit for all drivers. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds that results are per-driver and cover stints plus pit stops, which hints the tool combines data also exposed by get_stints and get_pit, but it says nothing about coverage gaps (e.g. sessions without tyre data) or ordering.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with zero filler; the resource comes first and the enumerated contents follow, so an agent can skim and act.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter read-only tool with full schema coverage, the description adequately conveys what comes back (compound sequence, stint lengths, pit stops). Minor gaps remain around whether the tool aggregates get_stints/get_pit output and whether data is returned for sessions with no pit activity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters, including the "latest" session alias and the driver_number array, are documented in the schema. The description's "for each driver in a session" only restates the schema's required/optional split, adding no new semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names the resource (tyre strategy), the scope (each driver in a session), and the concrete contents (compound sequence, stint lengths, pit stops), which lets an agent picture the payload. It does not, however, distinguish itself from siblings like get_stints or get_pit, which appear to return overlapping data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no statement of when to reach for this tool versus get_stints, get_pit, or get_laps, and no prerequisites such as a completed or live session. The agent must infer the choice purely from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_weatherWeatherBRead-onlyIdempotent
Track weather each minute: air and track temperature, humidity, pressure, rain, wind.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of records to return (default 200, max 1000). A summary is added when the result is larger. | |
| fields | No | Return only these attributes. Use this to make large results smaller. | |
| date_to | No | End of the time range (UTC, ISO 8601). Filters on "date" <= value. | |
| filters | No | Extra comparison filters, e.g. [{"field":"lap_duration","op":"<","value":90}]. Allowed fields: air_temperature, date, humidity, meeting_key, pressure, rainfall, session_key, track_temperature, wind_direction, wind_speed. Array fields cannot be filtered. | |
| rainfall | No | Only records with (true) or without (false) rain. | |
| date_from | No | Start of the time range (UTC, ISO 8601), e.g. "2025-11-09T17:05:00Z". Filters on "date" >= value. | |
| meeting_key | No | Meeting (Grand Prix weekend) identifier. Use "latest" for the current or most recent meeting. | |
| session_key | No | Session identifier. Use "latest" for the current or most recent session. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint and non-destructive, so the safety profile is covered. The description adds the per-minute sampling granularity and enumerates the observed fields, which is genuinely useful context, but says nothing about default limits, the summary that is appended to large result sets, or whether the data covers historical vs. live sessions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single compact sentence with no filler, front-loading the resource and measurement list. It is perhaps too terse for the tool's 8-param surface, but nothing in it is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 8 optional parameters and no output schema, the description covers what is returned but not how to retrieve it correctly — no mention that all parameters are optional, that omitting them returns all weather, or that 'latest' is the common scoping shortcut. An agent can still invoke it via the schema, but the description leaves important orientation work undone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and every parameter (limit, fields, filters, date_from/date_to, rainfall, meeting_key, session_key) is documented in the schema. The description's list of measurements loosely hints at the filterable attributes but adds no syntax, defaults, or semantics beyond the schema; baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names the resource (weather) and the specific measurements returned (air/track temperature, humidity, pressure, rain, wind) plus the per-minute granularity, which clearly separates it from lap, position, or telemetry siblings. It stops short of stating what the data is scoped to (session/meeting), so an agent must open the schema to learn that the records belong to an F1 session.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no indication of when to call this versus other tools, nor that it should typically be scoped with session_key or meeting_key (e.g. "latest"). There are no exclusions, prerequisites, or alternative tools named — the agent gets only the implied usage of 'track weather'.
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.
20 tool updates
v1.0.0- First observed
compare_fastest_laps - First observed
get_car_data - First observed
get_championship_drivers - First observed
get_championship_teams - First observed
get_drivers - First observed
get_intervals - First observed
get_laps - First observed
get_location - First observed
get_meetings - First observed
get_overtakes - First observed
get_pit - First observed
get_position - First observed
get_race_control - First observed
get_race_summary - First observed
get_session_result - First observed
get_sessions - First observed
get_starting_grid - First observed
get_stints - First observed
get_tyre_strategy - First observed
get_weather
TDQS
Scored across 20 tools
Several tools overlap in practice: get_session_result and get_race_summary both return session classifications/standings, while get_stints and get_tyre_strategy both expose tyre-stint information. get_pit also partially overlaps with get_tyre_strategy because strategy includes pit stops. Descriptions help, but an agent could still misselect among these related tools.
All tool names follow a clear snake_case verb_noun pattern, with get_* used for the vast majority and compare_fastest_laps as a natural action-specific variant. There is no mixing of camelCase, vague names, or inconsistent structural conventions.
Twenty tools is slightly heavy, but the F1 data domain is broad and each tool maps to a recognizable data type or analysis operation. The count is reasonable for the scope, though some redundancy among result, tyre, and pit tools keeps it from being perfectly scoped.
The surface covers the core F1 workflow very well: meetings, sessions, drivers, results, championships, laps, stints, pits, positions, intervals, race control, weather, telemetry, location, and fastest-lap comparison. Minor gaps remain, such as no explicit team-radio tool and no standalone teams endpoint beyond championship context.
Maintenance
Related MCP Connectors
Anonymous read-only Formula 1 tools, resources, prompts, completion, and interactive dashboard.
Read-only F1 game laps, telemetry, setups, leaderboard benchmarks, and progress.
Related MCP Servers
- AlicenseBqualityDmaintenanceProvides 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.5MIT
- FlicenseNot gradedqualityDmaintenanceEnables 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.-
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to query real-time and historical Formula 1 data through the OpenF1 API, providing tools for driver info, lap times, telemetry, race events, and more.MIT

mcp-f1official
AlicenseNot gradedqualityBmaintenanceProvides Formula 1 data via the Ergast API, enabling users to check current standings, get race results, view the season schedule, and look up driver profiles.9 npmMIT