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

# Response Envelopes and Partials

> Understand how Sports MCP Server communicates partial results, ambiguity, provenance, and recommended next steps.

# Response Envelopes and Partials

Sports MCP Server is explicit by design. A response can succeed and still tell you that one section was missing, ambiguous, or unsafe to enrich.

## Read the envelope before you deepen

| Field                                   | Why it matters                                                                                              |
| --------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `meta.partial`                          | Tells you the answer is usable but incomplete                                                               |
| `meta.missingSections`                  | Lists which parts of a bundle answer were intentionally not filled                                          |
| `meta.sources`                          | Preserves provenance across sports truth, program connectivity, current-state checks, and fallback evidence |
| `meta.crosswalkConfidence`              | Tells you whether cross-provider enrichment is safe for the selected result                                 |
| `meta.agentHints.recommendedNextTools`  | Gives the host ordered, non-binding next-step hints                                                         |
| `meta.agentHints.disambiguationOptions` | Helps you ask a narrowing question without guessing                                                         |
| `meta.limitations`                      | Explains known gaps, ambiguity, or upstream constraints                                                     |

## How to respond in the host

<Tabs>
  <Tab title="Complete enough result">
    A successful response with `partial: false` is usually safe to render directly.

    Good host behavior:

    * render the answer
    * preserve `meta.sources` for observability or QA
    * keep `meta.agentHints.recommendedNextTools` available only if the user drills down
  </Tab>

  <Tab title="Partial result">
    A partial result is not a failure. It is the server refusing to invent missing context.

    Good host behavior:

    * render the sections that are present
    * surface `meta.limitations` in product-appropriate language
    * avoid pretending the missing section is empty or negative
  </Tab>

  <Tab title="Ambiguous result">
    Ambiguity means the server needs a narrower scope, not that it picked the wrong tool.

    Good host behavior:

    * use `meta.agentHints.disambiguationOptions` to ask a tighter question
    * avoid silently selecting one candidate when `meta.crosswalkConfidence` is weak or `null`
    * preserve the original prompt and candidate set for the next turn
  </Tab>
</Tabs>

## Treat crosswalk confidence as a numeric workflow signal

| Band        | Meaning           | Safe host behavior                                                                     |
| ----------- | ----------------- | -------------------------------------------------------------------------------------- |
| `0.90-1.00` | High confidence   | Cross-provider enrichment may proceed when the product job requires it                 |
| `0.60-0.89` | Mixed confidence  | Do not silently deepen across providers; narrow scope or stay inside one source family |
| `0.01-0.59` | Low confidence    | Do not automatically cross providers                                                   |
| `null`      | No safe crosswalk | Do not assume linkage at all                                                           |

## Example response shapes

<Tabs>
  <Tab title="Partial bundle">
    ```json Partial bundle theme={null}
    {
      "meta": {
        "partial": true,
        "missingSections": ["watchAvailability"],
        "sources": [
          { "provider": "gsd_lookup", "role": "primary" },
          { "provider": "on_availability", "role": "secondary" }
        ],
        "crosswalkConfidence": null,
        "limitations": [
          "Watchability enrichment was skipped because cross-provider linkage was not strong enough."
        ],
        "agentHints": {
          "recommendedNextTools": ["get_watch_availability", "list_programs_for_entity"],
          "disambiguationOptions": []
        }
      },
      "data": {}
    }
    ```
  </Tab>

  <Tab title="Ambiguous resolution">
    ```json Ambiguous resolution theme={null}
    {
      "meta": {
        "partial": false,
        "crosswalkConfidence": null,
        "limitations": [
          "Resolution is request-time only and may need narrower sport context."
        ],
        "agentHints": {
          "recommendedNextTools": ["list_schedule"],
          "disambiguationOptions": [
            "Premier League",
            "Premier League Darts",
            "Premier League Rugby"
          ]
        }
      },
      "data": {}
    }
    ```
  </Tab>
</Tabs>

## Read this next

* [Protocol, Auth, and Errors](/sports-mcp-server/reference/protocol-auth-and-errors)
* [IDs, Crosswalks, and Bounded Windows](/sports-mcp-server/concepts/ids-crosswalks-and-bounded-windows)