Skip to main content
Glama
Sign In
withqwerty

football-docs

by withqwerty
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

resolve_entity

Read-only

Map football players, teams, competitions, and matches to provider IDs across Opta, Transfermarkt, Wyscout, and more using Reep ID, provider ID, or name lookups.

Instructions

Map a football entity (player, coach, referee, team, competition, season, stage or match) to its IDs at every provider through the Reep register: Opta, Transfermarkt, Wyscout, SkillCorner, StatsBomb, FotMob, API-Football and more. Look up by provider + id (pass namespace too, e.g. transfermarkt 'spieler', opta 'person'), by reep_id, or by name. Sources, in order: a local copy of the free register (REEP_DUCKDB_PATH), then the Reep API (REEP_API_KEY; keys are issued by hand on request, never self-service). With neither set, it returns setup steps and a DuckDB query. Keeping the local file current: Reep releases weekly. Every local answer ends with the file's release stamp checked against https://data.reep.football/releases/latest.json. If it says the file is out of date, tell the user and offer to run the curl command it gives, which downloads https://reep.football/downloads/duckdb over the same path; the next call uses the new file without a restart. Before bulk matching, make sure the file is current.

Input Schema

NameRequiredDescriptionDefault
idNoThe provider's own ID, used with provider
nameNoName to search, at least 3 characters (e.g. 'Declan Rice'). A name match is a shortlist, not an answer.
typeNoRestrict results to one entity type
reep_idNoA Reep ID (e.g. 'rp1b829f1d3468c4') to list every provider ID for
providerNoProvider key for an ID lookup, e.g. 'transfermarkt', 'opta', 'wyscout', 'skillcorner', 'fotmob'
namespaceNoThe provider's namespace for that ID, e.g. 'spieler' or 'verein' for Transfermarkt, 'person' or 'team' for Opta, 'player' for Wyscout. Recommended: some providers reuse numbers across entity types.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed8 schema fields changedv0.12.2
    • changedInput schema / properties / id / description
      Previous value: -"ID from the source provider to resolve to all other IDs"New value: +"The provider's own ID, used with provider"
    • changedInput schema / properties / name / description
      Previous value: -"Entity name to search for (e.g. 'Cole Palmer', 'Arsenal'). Fuzzy match on name and aliases."New value: +"Name to search, at least 3 characters (e.g. 'Declan Rice'). A name match is a shortlist, not an answer."
    • addedInput schema / properties / namespace
      Added value: +{
+  "description": "The provider's namespace for that ID, e.g. 'spieler' or 'verein' for Transfermarkt, 'person' or 'team' for Opta, 'player' for Wyscout. Recommended: some providers reuse numbers across entity types.",
+  "type": "string"
+}
    • changedInput schema / properties / provider / description
      Previous value: -"Source provider for ID resolution (e.g. 'transfermarkt', 'fbref', 'sofascore', 'opta', 'soccerway')"New value: +"Provider key for an ID lookup, e.g. 'transfermarkt', 'opta', 'wyscout', 'skillcorner', 'fotmob'"
    • removedInput schema / properties / qid
      Removed value: -{
-  "description": "Wikidata QID for direct lookup (e.g. 'Q99760796')",
-  "type": "string"
-}
    • addedInput schema / properties / reep_id
      Added value: +{
+  "description": "A Reep ID (e.g. 'rp1b829f1d3468c4') to list every provider ID for",
+  "type": "string"
+}
    • changedInput schema / properties / type / description
      Previous value: -"Filter results by entity type"New value: +"Restrict results to one entity type"
    • changedInput schema / properties / type / enum
      Previous value: -[
-  "player",
-  "team",
-  "coach"
-]New value: +[
+  "player",
+  "coach",
+  "referee",
+  "team",
+  "competition",
+  "season",
+  "stage",
+  "match"
+]
  2. First observedv0.6.4

TDQS

A4.5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only cover the read-only, open-world, non-destructive profile, but the description adds substantial behavior: the source fallback order (local DuckDB, then API), the exact degraded-mode return (setup steps plus a DuckDB query) when unconfigured, API key issuance policy, the release-stamp check against a live URL, the offer to run a curl download, and that the next call picks up the new file without a restart.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded in the first sentence and the mode/precedence information follows logically. The tail about weekly releases, the release-stamp URL, the curl command and the download URL is operational detail that is useful but dense; it could be tightened without losing meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a six-parameter, all-optional resolver with no output schema, the description covers inputs, sources, auth, degraded mode and freshness workflow well. The main gap is that it never sketches the shape of a successful result (e.g. one ID per provider), so an agent knows how to call it but not quite what to expect back.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is already 100%, so a 3 is the baseline, but the description adds value by explaining how parameters combine — 'look up by provider + id (pass namespace too, e.g. transfermarkt \'spieler\', opta \'person\')' — and by clarifying that a name match is a shortlist rather than an answer. It does not document the type enum or the id/reep_id fields beyond what the schema already says.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb ('Map... to its IDs') and resource (football entities in the Reep register), enumerates the entity types and target providers, and lists the three lookup modes. It is clearly distinguishable from siblings like resolve_provider_id because it scopes itself to cross-provider ID resolution via the Reep register.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives concrete conditional guidance: look up by provider+id (with namespace), by reep_id, or by name; and it states prerequisites such as REEP_DUCKDB_PATH / REEP_API_KEY, that keys are issued by hand, and that the file should be current before bulk matching. What it never does is name a sibling alternative (e.g. resolve_provider_id) or state when NOT to use this tool, so it falls short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools