> ## 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. # Resolve Entities > Resolve fuzzy sports language into bounded sport, competition, season, series, and participant candidates. Canonical tool name: `resolve_entities` Family: [Resolution and Scope Tools](/sports-mcp-server/tools/resolution-and-scope-tools) ## What this tool is best at Resolve fuzzy sports language into bounded candidates with provider refs, crosswalk confidence, and disambiguation options. ## Choose this tool when * the host does not yet know which sport, competition, competition season, series, participant, or venue the user means. * Source ownership: GSD Lookup primary ## Use something smaller or different when * the caller already has a stable provider ref and only needs schedule, standings, watchability, or event detail. ## 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 | | ------- | ------------------------------------------------------------------------------------------------------------------------------ | | `query` | Free-text sports prompt fragment to resolve. Include the league, team, player, venue, or event wording the user actually used. | ### Optional inputs in the public contract | Input | What it means | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `entityType` | Optional narrowing hint. Pass this when the host already knows the user is asking for a competition, participant, event, or venue. | | `resolutionProfile` | Optional traversal depth. Leave it on `balanced` for normal UX, use `fast` when latency matters more than coverage, and use `complete` only for non-participant entity types. | | `resolutionIntent` | Optional intent hint for ambiguous families. Use `rankings` when ATP, WTA, or similar series names could map to Race, Ranking, or other sibling leaderboards. | | `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 * Use `entityType` when the host already knows the kind of thing the user means and wants tighter candidate ranking. * Use `resolutionIntent` when one lexical family maps to multiple sibling series and the host already knows the next view it wants, such as rankings. * Use `limit` to keep candidate sets compact for low-token flows. * Use `resolutionProfile` to trade off latency against exhaustive live traversal. `complete` is supported for non-participant entity types only and may be materially slower because it exhausts the live frontier instead of stopping early. * `crosswalkConfidence` is scored per candidate on a `0.00-1.00` scale. Treat `0.90-1.00` as high confidence, `0.60-0.89` as mixed confidence that should not silently deepen across providers, `0.01-0.59` as low confidence, and `null` as no crosswalk. ## 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. | * Pick one candidate and preserve its provider refs before calling a deeper tool. * Use `crosswalkConfidence` to decide whether hybrid enrichment is safe or whether the host should ask a narrowing question. ## Response highlights * Bounded candidate rows with `entityType`, `displayName`, `participantType` for participant rows, `gsdRefs`, `onRefs`, and `programHints`. * Crosswalk confidence that tells the host whether it can safely enrich across providers or should ask a narrowing question first. * Machine-readable `data.traversal` metadata that tells the host which live frontier was explored, whether it was complete, and where coverage stayed partial. * Candidate ordering is deterministic: intent fit first, then lexical score, then lexical tie-breaks, then entity-type ordering, then stable ID. ## Response shape | Field | What it means | | --------------------------------------------------- | ------------------------------------------------------------------------------------ | | `data.query` | Echo of the caller query. | | `data.candidates[]` | Ranked candidate rows across supported sports entity classes. | | `data.candidates[].entityType` | Resolved entity class for each candidate. | | `data.candidates[].displayName` | Prompt-ready label for host disambiguation and display. | | `data.candidates[].gsdRefs / onRefs / programHints` | Reusable provider refs and secondary hints for the next step. | | `data.candidates[].crosswalkConfidence` | Per-candidate cross-provider safety score, or `null` when no safe crosswalk exists. | | `data.traversal` | Coverage and traversal metadata describing what the resolver explored. | | `meta.agentHints.disambiguationOptions[]` | Prompt-ready narrowing labels derived from the highest-ranked unresolved candidates. | | `meta.agentHints.recommendedNextTools[]` | Non-binding next-step hints such as schedule, hub, or watchability flows. | ## Reuse next * `gsdRefs` for GSD-first tools such as `list_schedule`, `get_competition_hub`, `get_event_summary`, and `get_standings`. * `onRefs` for program-context and watchability flows such as `get_program_context`, `get_watch_availability`, and `list_programs_for_entity`. ## Example requests ```json JSON-RPC theme={null} { "jsonrpc": "2.0", "id": "tool-call-1", "method": "tools/call", "params": { "name": "resolve_entities", "arguments": { "query": "Premier League", "entityType": "competition", "resolutionProfile": "balanced", "resolutionIntent": "generic", "limit": 5 } } } ``` ```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": "resolve_entities", "arguments": { "query": "Premier League", "entityType": "competition", "resolutionProfile": "balanced", "resolutionIntent": "generic", "limit": 5 } } }' ``` ```ts TypeScript theme={null} const payload = { "jsonrpc": "2.0", "id": "tool-call-1", "method": "tools/call", "params": { "name": "resolve_entities", "arguments": { "query": "Premier League", "entityType": "competition", "resolutionProfile": "balanced", "resolutionIntent": "generic", "limit": 5 } } }; 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": "resolve_entities", "arguments": { "query": "Premier League", "entityType": "competition", "resolutionProfile": "balanced", "resolutionIntent": "generic", "limit": 5 } } } 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 * No common previous-step tools beyond already knowing the right IDs or scope. ### Next-step tools * [`list_schedule`](/sports-mcp-server/tool-reference/list_schedule) * [`get_competition_hub`](/sports-mcp-server/tool-reference/get_competition_hub) * [`list_watchable_schedule`](/sports-mcp-server/tool-reference/list_watchable_schedule) * [`get_program_context`](/sports-mcp-server/tool-reference/get_program_context) ### Alternative tools * No common alternatives. ## Prompt patterns this tool fits * "Resolve this league/team/event first." * "I don’t know which IDs I need yet." ## Common mistakes * Treating provider refs like server-generated canonical IDs. The caller must preserve whether a ref came from GSD or On. * Using it as a replacement for a direct profile or schedule call after the IDs are already known.