Skip to main content

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.

Canonical tool name: resolve_entities Family: 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

InputWhat it means
queryFree-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

InputWhat it means
entityTypeOptional narrowing hint. Pass this when the host already knows the user is asking for a competition, participant, event, or venue.
resolutionProfileOptional 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.
resolutionIntentOptional intent hint for ambiguous families. Use rankings when ATP, WTA, or similar series names could map to Race, Ranking, or other sibling leaderboards.
limitMaximum number of rows to return. Keep it small for low-token UX and larger only when the UI truly needs a browse list.
languageOptional 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 scopeCall this firstThen use
scopeTool CatalogStart 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

FieldWhat it means
data.queryEcho of the caller query.
data.candidates[]Ranked candidate rows across supported sports entity classes.
data.candidates[].entityTypeResolved entity class for each candidate.
data.candidates[].displayNamePrompt-ready label for host disambiguation and display.
data.candidates[].gsdRefs / onRefs / programHintsReusable provider refs and secondary hints for the next step.
data.candidates[].crosswalkConfidencePer-candidate cross-provider safety score, or null when no safe crosswalk exists.
data.traversalCoverage 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

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

​
Previous-step tools

  • No common previous-step tools beyond already knowing the right IDs or scope.

​
Next-step tools

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