Discovery and Resolution Tools

​

Start Here If

• you need to confirm what sports, leagues, or series the account can cover
• the user typed a fuzzy name like “Salah”, “Man Utd”, or “Formula 1”
• you want a live or upcoming schedule without already knowing a match ID
• you are building onboarding, search, or import flows that need canonical IDs

​

Tool Selection Guide

​

Catalog Discovery

​

gns_list_sports

• What it helps you do: discover which sports your entitlement covers.
• When to use it: day-one evaluation, sport pickers, or coverage checks.
• Inputs you need: optional language.
• What you get back: sport IDs, names, and basic sport metadata.
• Example user questions it can answer: “Which sports can this assistant cover?”
• Example request:

{
  "name": "gns_list_sports",
  "arguments": {
    "language": "en-US"
  }
}

• Expected response summary: a list of sports you can reuse in league discovery or scoreboard flows.
• What to call next: gns_list_leagues, gns_get_sport, or gns_sports_dayboard.

​

gns_get_sport

• What it helps you do: inspect one known sport ID.
• When to use it: you already have a sportId and need localized sport metadata.
• Inputs you need: sportId, optional language.
• What you get back: one sport object with IDs, names, and metadata.
• Example user questions it can answer: “What does this sport ID represent?”
• Example request:

{
  "name": "gns_get_sport",
  "arguments": {
    "sportId": "SPORT_ID",
    "language": "en-US"
  }
}

• Expected response summary: one sport record you can display or use to confirm scope.
• What to call next: gns_list_leagues or gns_schedule_results.

​

gns_list_leagues

• What it helps you do: discover leagues across the entitlement or within a single sport.
• When to use it: league pickers, onboarding screens, or coverage audits.
• Inputs you need: optional sportId, optional language.
• What you get back: league IDs, names, and their associated sport.
• Example user questions it can answer: “Which football leagues can this product support?”
• Example request:

{
  "name": "gns_list_leagues",
  "arguments": {
    "sportId": "SPORT_ID",
    "language": "en-US"
  }
}

• Expected response summary: a league catalog you can feed into schedule, standings, or season workflows.
• What to call next: gns_get_league, gns_schedule_results, or gns_live_league_dashboard.

​

gns_list_series

• What it helps you do: discover series or championship groupings that span more than one league.
• When to use it: motorsport or multi-league championship experiences.
• Inputs you need: optional sportId, optional language.
• What you get back: series IDs, names, and sport associations.
• Example user questions it can answer: “Which racing series are available?”
• Example request:

{
  "name": "gns_list_series",
  "arguments": {
    "sportId": "SPORT_ID",
    "language": "en-US"
  }
}

• Expected response summary: a list of series you can pass into series overview and championship tools.
• What to call next: gns_get_series or gns_series_championship_snapshot.

​

Schedule Discovery

​

gns_schedule_results

• What it helps you do: answer “what’s on”, “what just happened”, and “what does this league or team play next?”
• When to use it: scoreboards, daily widgets, live assistants, or targeted schedule windows.
• Inputs you need: timeFrom, timeTo, plus optional sportId, leagueId, teamId, or tierId.
• What you get back: matches with IDs, participants, scores, dates, venues, and status.
• Example user questions it can answer: “What NBA games are on tonight?” and “What is this team’s schedule for the next month?”
• Example request:

{
  "name": "gns_schedule_results",
  "arguments": {
    "timeFrom": "2026-03-18",
    "timeTo": "2026-03-20",
    "language": "en-US"
  }
}

{
  "name": "gns_schedule_results",
  "arguments": {
    "leagueId": "LEAGUE_ID",
    "timeFrom": "2026-03-18",
    "timeTo": "2026-03-20",
    "language": "en-US"
  }
}

{
  "name": "gns_schedule_results",
  "arguments": {
    "leagueId": "LEAGUE_ID",
    "teamId": "TEAM_ID",
    "timeFrom": "2026-03-18",
    "timeTo": "2026-03-31",
    "language": "en-US"
  }
}

• Expected response summary: a time-bounded schedule or results list with match IDs you can use in match tools or live bundles.
• What to call next: gns_matchboard, gns_match_info, gns_live_league_dashboard, or gns_team_info.

​

gns_team_schedule_results

• What it helps you do: fetch one team’s schedule across all leagues instead of only one league context.
• When to use it: team hubs, follow flows, or cross-competition assistant prompts.
• Inputs you need: teamId, timeFrom, timeTo, optional language.
• What you get back: cross-league schedule and results for the selected team.
• Example user questions it can answer: “Show me Inter Miami’s next 30 days across competitions.”
• Example request:

{
  "name": "gns_team_schedule_results",
  "arguments": {
    "teamId": "TEAM_ID",
    "timeFrom": "2026-03-18",
    "timeTo": "2026-04-18",
    "language": "en-US"
  }
}

• Expected response summary: one team’s upcoming and recent matches across leagues.
• What to call next: gns_team_info, gns_team_season_profile, or gns_matchboard.

​

Entity Resolution

​

gns_resolve_entity

• What it helps you do: turn one fuzzy sports phrase into ranked candidate IDs.
• When to use it: the user typed a name, nickname, abbreviation, or ambiguous term.
• Inputs you need: query, optional type, optional sportId, optional leagueId, optional limit.
• What you get back: ranked candidates with type, ID, and confidence.
• Example user questions it can answer: “What does Salah refer to in this league?” and “Which United team is this user talking about?”
• Example request:

{
  "name": "gns_resolve_entity",
  "arguments": {
    "query": "Premier League",
    "type": "league",
    "limit": 5
  }
}

{
  "name": "gns_resolve_entity",
  "arguments": {
    "query": "Salah",
    "type": "person",
    "leagueId": "LEAGUE_ID",
    "limit": 10
  }
}

• Expected response summary: a ranked candidate list you can choose from or pass automatically into the next call.
• What to call next: almost any deeper tool, depending on the returned entity type.

​

gns_resolve_batch

• What it helps you do: resolve many names in one network call.
• When to use it: ingestion jobs, onboarding, migrations, or search indexing.
• Inputs you need: queries[], where each query can carry its own type, sportId, leagueId, and limit.
• What you get back: one ranked result set per query plus batch metadata.
• Example user questions it can answer: “Map these ten team names before I import them.”
• Example request:

{
  "name": "gns_resolve_batch",
  "arguments": {
    "queries": [
      {
        "query": "Lakers",
        "type": "team",
        "limit": 5
      },
      {
        "query": "Bundesliga",
        "type": "league",
        "limit": 5
      }
    ]
  }
}

• Expected response summary: parallel result sets with ranked candidates for each requested phrase.
• What to call next: whichever tool matches the winning ID for each row.

​

gns_resolve_many

• What it helps you do: page through larger candidate sets when ambiguity is high.
• When to use it: search UIs, curation flows, or import tooling that needs deterministic pagination.
• Inputs you need: queries[], pageSize, and optional cursor.
• What you get back: candidate sets with offset, hasMore, nextCursor, and per-query results.
• Example user questions it can answer: “Give me every plausible result for United, then page through them.”
• Example request:

{
  "name": "gns_resolve_many",
  "arguments": {
    "queries": [
      {
        "queryId": "q-1",
        "query": "United",
        "type": "team",
        "limit": 50
      }
    ],
    "pageSize": 10
  }
}

• Expected response summary: candidate windows with paging metadata suitable for human review or multi-step agent selection.
• What to call next: the deeper tool that matches the chosen ID, or gns_resolve_many again with the returned nextCursor.

​

Recommended Pattern

1. discover or resolve the right canonical ID
2. fetch the schedule or product context you actually need
3. only then call deeper match, season, or watchability tools