> ## 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 Watchable Schedule > Return bounded schedule rows enriched with grounded watchability semantics when available, otherwise return truthful evidence-backed fallback rows with explicit limitations. Canonical tool name: `list_watchable_schedule` Family: [Resolution and Scope Tools](/sports-mcp-server/tools/resolution-and-scope-tools) ## What this tool is best at Return bounded schedule rows enriched with grounded watchability semantics when available, otherwise return truthful evidence-backed fallback rows with explicit limitations. ## Choose this tool when * the user is really asking what can be watched in a bounded window. * Source ownership: Dedicated availability primary when provisioned, otherwise bounded sports-truth rows plus explicit fallback watchability evidence ## Use something smaller or different when * the answer must stay purely competition-first or when the host needs standings, actions, or stats. ## Inputs you need ### Plain-English prerequisites * `competitionId / competitionSeasonId / participantId / sportId / seriesId / seriesSeasonId / venueId`: Use the best available scoped ref plus a bounded `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` | Resolved sport ref for a sport-wide watchability browse scope. | | `competitionId` | Resolved competition ref for one watchability browse scope. | | `competitionSeasonId` | Provider ref for one competition season. Use it when the host needs a season-specific table, ranking, structure, or roster context. | | `seriesId` | Resolved series ref for a tour-wide or motorsport watchability browse scope. | | `seriesSeasonId` | Provider ref for one series season. Use it when the host needs one tour season instead of the broader series. | | `participantId` | Resolved participant ref when the user wants a team- or person-led watchable rail. | | `venueId` | Venue ref for venue-led browse or venue-filtered watchability experiences. Preserve the provider namespace from the earlier step. | | `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 the selected row to branch into `get_watch_availability` for a direct where-to-watch answer or into `list_live_slate` for now-playing context. * Do not swap this tool in for `list_schedule` just because the argument names look similar. ## Response highlights * Rows live in `data.items[]` and preserve the schedule shape while adding watchability-specific fields. * `data.availabilityMode` tells the host whether the response is operating in proven dedicated mode, evidence-only mode, or no-watchability mode. * Each row may include grounded programs, fallback event evidence, and explicit linkage status without inventing channels or services. ## Response shape | Field | What it means | | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | `data.items[]` | Bounded watchable schedule rows for the selected scope and window. | | `data.items[].watchabilityProven` | Whether the row is backed by dedicated availability rather than fallback evidence. | | `data.items[].linkageStatus` | Per-row trust state: `proven`, `unresolved`, or `provider_unavailable`. | | `data.items[].programs[]` | Program rows when dedicated availability exposes grounded linkage. | | `data.items[].eventEvidence` | Fallback event evidence when the row cannot be proven as watchable. | | `data.items[].scheduleStatus / resultStatus / showInSchedule / onCurrentStatus` | Current-state and guide-style evidence hints when exposed. | | `data.availabilityMode` | Overall response mode: `dedicated`, `on_evidence`, or `none`. | | `data.scope` | Echo of the selected browse scope and bounded window. | ## 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_watchable_schedule", "arguments": { "competitionId": "COMPETITION_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_watchable_schedule", "arguments": { "competitionId": "COMPETITION_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_watchable_schedule", "arguments": { "competitionId": "COMPETITION_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_watchable_schedule", "arguments": { "competitionId": "COMPETITION_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 * [`list_live_slate`](/sports-mcp-server/tool-reference/list_live_slate) * [`get_watch_availability`](/sports-mcp-server/tool-reference/get_watch_availability) ### Alternative tools * [`list_schedule`](/sports-mcp-server/tool-reference/list_schedule) ## Prompt patterns this tool fits * Use `list_watchable_schedule` when the host already knows the right scope and needs this job directly. ## Common mistakes * Using it as a substitute for GSD schedule detail when the host really needs pure competition truth. * Assuming every schedule row is watchable instead of reading the returned watchability evidence and limitations.