> ## 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 Programs For Entity

> Return raw program-linkage evidence for a sports entity.

Canonical tool name: `list_programs_for_entity`

Family: [Program Connectivity and Watchability Tools](/sports-mcp-server/tools/program-connectivity-and-watchability-tools)

## What this tool is best at

Return compact raw evidence linking a sports entity to programs.

## Choose this tool when

* the host needs the raw graph before it normalizes watchability.
* Source ownership: Dedicated availability primary when provisioned, otherwise fallback event/program evidence with explicit linkage limitations

## Use something smaller or different when

* the product wants a polished where-to-watch answer; use `get_watch_availability` instead.

## Inputs you need

### Plain-English prerequisites

* This tool does not require a prerequisite ID beyond the scoped inputs shown below.

### Required inputs in the public contract

| Input        | What it means                                                                                                                                     |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `entityId`   | Entity ref for the selected sport, competition, season, event, participant, or venue. Use the same namespace you preserved from the earlier step. |
| `entityType` | Entity kind for `entityId`. This tells the server which program-lookup parameters it should emit.                                                 |

### Optional 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.               |
| `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.                                                                           |

### Notes on optional inputs

* `timeFrom` and `timeTo` are optional here. If you provide one, provide both so the linkage evidence remains bounded.

## 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. |

## Response highlights

* Return compact raw evidence linking a sports entity to programs.

## Response shape

| Field                             | What it means                                                                         |
| --------------------------------- | ------------------------------------------------------------------------------------- |
| `data.entityId / data.entityType` | Echo of the requested sports entity scope.                                            |
| `data.programs[]`                 | Program rows when dedicated entity-to-program linkage can be proven.                  |
| `data.events[]`                   | Event evidence rows when only fallback evidence exists.                               |
| `data.availabilityMode`           | Whether the answer is using dedicated linkage, evidence-only fallback, or no linkage. |

## 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

<CodeGroup>
  ```json JSON-RPC theme={null}
  {
    "jsonrpc": "2.0",
    "id": "tool-call-1",
    "method": "tools/call",
    "params": {
      "name": "list_programs_for_entity",
      "arguments": {
        "entityId": "ON_EVENT_GID",
        "entityType": "event",
        "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_programs_for_entity",
      "arguments": {
        "entityId": "ON_EVENT_GID",
        "entityType": "event",
        "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_programs_for_entity",
        "arguments": {
          "entityId": "ON_EVENT_GID",
          "entityType": "event",
          "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_programs_for_entity",
      "arguments": {
        "entityId": "ON_EVENT_GID",
        "entityType": "event",
        "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))
  ```
</CodeGroup>

## Related tools

### Previous-step tools

* [`resolve_entities`](/sports-mcp-server/tool-reference/resolve_entities)

### Next-step tools

* [`get_watch_availability`](/sports-mcp-server/tool-reference/get_watch_availability)
* [`get_program_context`](/sports-mcp-server/tool-reference/get_program_context)

### Alternative tools

* No common alternatives.

## Prompt patterns this tool fits

* Use `list_programs_for_entity` when the host already knows the right scope and needs this job directly.

## Common mistakes

* Calling `list_programs_for_entity` before the host has the right provider refs or bounded window.
* Using `list_programs_for_entity` when a smaller sibling tool would answer the question more directly.