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

Complete enough result
Partial result
Ambiguous 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

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

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

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

Partial bundle
Ambiguous resolution

Partial bundle

{
  "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": {}
}

Ambiguous resolution

{
  "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": {}
}

Getting Started

Concepts

Guides

Tools

Tool Reference

Reference

Response Envelopes and Partials

Response Envelopes and Partials

Read the envelope before you deepen

How to respond in the host

Treat crosswalk confidence as a numeric workflow signal

Example response shapes

Read this next

​Response Envelopes and Partials

​Read the envelope before you deepen

​How to respond in the host

​Treat crosswalk confidence as a numeric workflow signal

​Example response shapes

​Read this next

Response Envelopes and Partials

Read the envelope before you deepen

How to respond in the host

Treat crosswalk confidence as a numeric workflow signal

Example response shapes

Read this next