> ## Documentation Index > Fetch the complete documentation index at: https://docs.etonecarg.com/llms.txt > Use this file to discover all available pages before exploring further. # List Schedule > Return the smallest sufficient sports schedule rows for a bounded competition, season, series, sport, or participant scope. Canonical tool name: `list_schedule` Family: [Resolution and Scope Tools](/sports-mcp-server/tools/resolution-and-scope-tools) ## What this tool is best at Return the competitive deep-sports schedule for a bounded sport, competition, competition season, series, series season, or participant scope. ## Choose this tool when * the question is about the sports calendar itself and GSD should remain the source of truth. * Source ownership: GSD Lookup primary ## Use something smaller or different when * the product is explicitly asking what is watchable; use `list_watchable_schedule` or `list_live_slate` instead. ## Inputs you need ### Plain-English prerequisites * `sportId / seriesId / seriesSeasonId / competitionId / competitionSeasonId / participantId`: Provide one bounded schedule anchor plus `timeFrom` and `timeTo`. ### Required inputs in the public contract | Input | What it means | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `timeFrom` | Bounded window start. Use an ISO date or timestamp that matches the user’s browse moment or watchability horizon. Some tools require this field as part of the public contract. | | `timeTo` | Bounded window end. Keep it tight enough that the request still represents one real product moment. Some tools require this field as part of the public contract. | ### Optional inputs in the public contract | Input | What it means | | --------------------- | ----------------------------------------------------------------------------------------------------------------------- | | `sportId` | GSD-facing sport ref for a sport-wide schedule query. | | `competitionId` | GSD-facing competition ref for a competition-first schedule query. | | `competitionSeasonId` | GSD-facing season ref when the host wants one competition season instead of the broader competition. | | `seriesId` | GSD-facing series ref for a tour-wide or motorsport schedule query. | | `seriesSeasonId` | GSD-facing series-season ref when the host wants one tour season window. | | `participantId` | GSD-facing participant ref when the schedule should be anchored to one team or participant. | | `limit` | Maximum number of rows to return. Keep it small for low-token UX and larger only when the UI truly needs a browse list. | | `language` | Optional BCP 47 language hint such as `en-US`. Use it when the host needs translated provider output. | ## Sequencing guidance | Needed ID or scope | Call this first | Then use | | ------------------ | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | scope | [Tool Catalog](/sports-mcp-server/tools/tool-catalog) | Start from the smallest tool that can safely anchor the workflow, then deepen only if the user asks for more. | * Use this tool to identify the right event row before opening deeper event tools. * Stay in GSD-first tools after this call unless the UX explicitly shifts into watchability. ## Response highlights * Top-level schedule rows are returned in `data.items[]`; there is no separate `data.schedule[]` object in the public contract. * Each row carries the reusable event refs, compact participant summary, status, and any exposed `phaseRefs` or `overallRefs`. * The response also returns `data.scope` and `data.seasonFilterApplied` so the host can see the final bounded browse scope. ## Response shape | Field | What it means | | ------------------------------------------ | --------------------------------------------------------------------- | | `data.items[]` | Bounded schedule rows for the selected scope and time window. | | `data.items[].eventId` | Reusable event ref for later event-detail calls. | | `data.items[].sportsEventGId` | Secondary event-evidence ref when the selected row exposes it. | | `data.items[].name / startTime / status` | Compact event identity and timing fields for list rendering. | | `data.items[].participants[]` | Compact participant-side summary for each schedule row. | | `data.items[].phaseRefs[] / overallRefs[]` | Actionable deeper refs when the upstream row exposes them. | | `data.scope` | Echo of the final browse scope and bounded window used by the server. | | `data.seasonFilterApplied` | Whether the server narrowed the result to a season-specific slice. | ## Reuse next * Reuse provider refs returned by this tool to avoid resolving the same entity again. * Read `meta.agentHints.recommendedNextTools` and `meta.agentHints.disambiguationOptions` as non-binding host hints. ## Example requests ```json JSON-RPC theme={null} { "jsonrpc": "2.0", "id": "tool-call-1", "method": "tools/call", "params": { "name": "list_schedule", "arguments": { "competitionId": "LEAGUE_ID", "timeFrom": "2026-04-08", "timeTo": "2026-04-09" } } } ``` ```bash curl theme={null} curl "https://sports-mcp-server.etonecarg.com/" \ -X POST \ -H "Authorization: Bearer $SPORTS_MCP_API_KEY" \ -H "Accept: application/json, text/event-stream" \ -H "Content-Type: application/json" \ -H "mcp-protocol-version: 2025-03-26" \ -d '{ "jsonrpc": "2.0", "id": "tool-call-1", "method": "tools/call", "params": { "name": "list_schedule", "arguments": { "competitionId": "LEAGUE_ID", "timeFrom": "2026-04-08", "timeTo": "2026-04-09" } } }' ``` ```ts TypeScript theme={null} const payload = { "jsonrpc": "2.0", "id": "tool-call-1", "method": "tools/call", "params": { "name": "list_schedule", "arguments": { "competitionId": "LEAGUE_ID", "timeFrom": "2026-04-08", "timeTo": "2026-04-09" } } }; const response = await fetch("https://sports-mcp-server.etonecarg.com/", { method: "POST", headers: { Authorization: `Bearer ${process.env.SPORTS_MCP_API_KEY!}`, Accept: "application/json, text/event-stream", "Content-Type": "application/json", "mcp-protocol-version": "2025-03-26", }, body: JSON.stringify(payload), }); const data = await response.json(); console.log(JSON.stringify(data, null, 2)); ``` ```python Python theme={null} import json import os import requests payload = { "jsonrpc": "2.0", "id": "tool-call-1", "method": "tools/call", "params": { "name": "list_schedule", "arguments": { "competitionId": "LEAGUE_ID", "timeFrom": "2026-04-08", "timeTo": "2026-04-09" } } } response = requests.post( "https://sports-mcp-server.etonecarg.com/", headers={ "Authorization": f"Bearer {os.environ['SPORTS_MCP_API_KEY']}", "Accept": "application/json, text/event-stream", "Content-Type": "application/json", "mcp-protocol-version": "2025-03-26", }, json=payload, timeout=30, ) response.raise_for_status() print(json.dumps(response.json(), indent=2)) ``` ## Related tools ### Previous-step tools * [`resolve_entities`](/sports-mcp-server/tool-reference/resolve_entities) ### Next-step tools * [`get_event_summary`](/sports-mcp-server/tool-reference/get_event_summary) * [`get_competition_hub`](/sports-mcp-server/tool-reference/get_competition_hub) ### Alternative tools * [`list_watchable_schedule`](/sports-mcp-server/tool-reference/list_watchable_schedule) * [`list_live_slate`](/sports-mcp-server/tool-reference/list_live_slate) ## Prompt patterns this tool fits * Use `list_schedule` when the host already knows the right scope and needs this job directly. ## Common mistakes * Using an open-ended window. All schedule flows are intentionally bounded. * Assuming GSD schedule rows imply watchability. They do not.