This server provides AI agents with searchable access to football data documentation, cross-provider comparison, and entity resolution. You can:
Search documentation: Full-text search across 1,356 documentation chunks from 21 providers (e.g., StatsBomb, Opta, Wyscout) with provider and result count filters.
Resolve provider names: Map aliases or informal names to canonical provider keys (e.g., "Stats Perform" → "opta").
Retrieve provider docs: Get detailed documentation for a specific provider, optionally filtered by topic or category (e.g., api-endpoints, xG).
List providers: See all indexed providers, their document counts, and coverage categories.
Compare providers: Understand how different providers handle the same concept (e.g., shot events, coordinate systems).
Request updates: Flag outdated docs, suggest new providers, or request recrawls, queued for review.
Resolve entities: Map players, teams, or coaches across provider IDs (e.g., Transfermarkt, FBref, Opta) via names, IDs, or Wikidata QIDs.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@football-docs What is Opta qualifier 76?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Searchable football data provider and tooling documentation for AI coding agents. Like Context7 for football data.
Who it's for: Developers and analysts who use AI coding tools (Claude Code, Cursor, VS Code Copilot) to work with football data. Works with any tool that supports MCP.
What it does: Gives your AI agent a searchable index of documentation for 23 football data providers and tools — event types, qualifier IDs, coordinate systems, API endpoints, data models, identity surfaces, and cross-provider comparisons for the data providers (StatsBomb, Opta, Wyscout, Impect, SkillCorner, Sportradar, TheSportsDB, FMDB Pro, TransferRoom, and more), plus the open-source libraries people build with (kloppy, mplsoccer, socceraction, soccerdata, floodlight, fast-forward, unravelsports, and more). Your agent looks up the real docs instead of guessing from training data.
Why not just let the AI figure it out? LLMs get football data specifics wrong constantly — Opta qualifier IDs, StatsBomb coordinate ranges, API endpoint URLs, library method signatures. These are mutable facts that change across versions. football-docs gives the agent verified, sourced documentation with provenance tracking so you know where every answer came from.
football-docs is intended to be a community-owned, source-transparent Context7 for football data. The public operating contract is in STRATEGY.md: what belongs here, what must stay out, how we handle public-safe provider facts, and how contributors should prove retrieval quality.
Related MCP server: Unified Docs Hub
football-docs is the public source for provider identity-surface facts: access shape, ID schemes, matching fields, provider quirks, and provenance rules. Curated provider identity notes belong here when they can be stated as public facts about the provider. They should say whether a fact comes from public docs, public page evidence, licensed feed shape, or a reviewed public-safe observation, and must not include credentials, local paths, internal tooling details, or restricted payloads from any private project.
MCP (Model Context Protocol) is a standard for connecting AI coding tools to external data sources.
claude mcp add football-docs -- npx -y football-docsSettings → MCP → Add server. Use this config:
{
"mcpServers": {
"football-docs": {
"command": "npx",
"args": ["-y", "football-docs"]
}
}
}Add to .vscode/mcp.json:
{
"servers": {
"football-docs": {
"command": "npx",
"args": ["-y", "football-docs"]
}
}
}Add to claude_desktop_config.json:
{
"mcpServers": {
"football-docs": {
"command": "npx",
"args": ["-y", "football-docs"]
}
}
}Tool | Description |
| Full-text search across all provider docs. Filter by provider. Results include provenance (source URL, version). |
| Resolve provider names and aliases to canonical indexed provider keys before searching. |
| Retrieve docs for a resolved provider, optionally filtered by topic or category. |
| List all indexed providers and their doc coverage. |
| Compare how different providers handle the same concept. |
| Request a new provider, flag outdated docs, or suggest a better doc source. Queues locally and points to the matching public GitHub issue template. |
| Resolve players, teams, or coaches to cross-provider IDs via the Reep API. |
Provider filters use the indexed provider keys shown by list_providers, but common aliases are accepted. Examples: fbref, understat, ClubElo, football-data.co.uk, and engsoccerdata search free-sources; Sofascore and ESPN search soccerdata; FMDB searches fmdb-pro; Transfer Room searches transferroom; Hudl Wyscout searches wyscout; Stats Perform / Opta F24 / WhoScored search opta; Metrica, Sportec / DFL, and TRACAB search databallpy; Second Spectrum searches kloppy; Hawk-Eye, SciSports, Signality, Respovision, GradientSports and OptaVision search fast-forward; unravel searches unravelsports; SportRadar API / Soccer Extended search sportradar; The Sports DB / TSDB search thesportsdb; StatsBomb Open Data searches statsbomb.
"What is Opta qualifier 76?" (big chance)
"How does StatsBomb represent shot events?"
"Compare Opta and Wyscout coordinate systems"
"What player ID fields does Transfermarkt expose?"
"Does SportMonks have xG data?"
"What event types does kloppy map to GenericEvent?"
"How does SPADL represent a tackle?"
Provider | Chunks | Categories |
fast-forward | 250 | overview, getting-started, data-model, coordinate-system, orientations, layouts, transformations, distributed-compute, api-reference, 12 provider format pages |
StatsBomb | 235 | event-types, data-model, coordinate-system, api-access, api-endpoints, charting-lineups, xg-model, iq-metrics, player/team stats, player-mapping, identity-surfaces |
unravelsports | 202 | overview, installation, quickstart, concepts, graph converters, pressing intensity, formation detection, models, utils, american-football |
Wyscout | 163 | event-types, data-model, coordinate-system, api-access, api-endpoints, charting-analysis-metrics, glossary, identity-surfaces |
kloppy | 126 | data-model, usage, provider-mapping, tracking-rendering, event-derived-metrics |
floodlight | 144 | core data objects, io parsers (Tracab, DFL, Kinexon, Opta, SkillCorner, StatsBomb, StatsPerform, Second Spectrum), transforms, metrics, models, visualisation, guides |
SportMonks | 565 | full v3 endpoint reference (fixtures, livescores, leagues, seasons, states, types, statistics, brackets), syntax and includes, filtering, rate limits, error codes, changelog, plus curated event-types, data-model, api-access, charting-season-stories, identity-surfaces |
databallpy | 63 | data-model, overview, usage |
mplsoccer | 65 | overview, pitch-types, visualizations |
Impect | 77 | overview, data-model, event-types, coordinate-system, concepts, kpi-definitions, identity-surfaces |
SkillCorner | 49 | api-access, api-endpoints, data-model, physical-data, coordinate-system, concepts, identity-surfaces |
Free sources | 62 | overview, fbref, understat, contextual-story-joins, xg-timelines |
soccerdata | 40 | overview, data-sources, usage |
TransferRoom | 43 | api-access, api-endpoints, charting-availability, data-model, identity-surfaces |
Opta | 71 | event-types, qualifiers, coordinate-system, api-access, charting-game-state, charting-lineups, charting-passmaps, charting-set-pieces, charting-shot-placement, identity-surfaces |
FMDB Pro | 35 | api-access, api-endpoints, data-model, identity-surfaces |
Sportradar | 30 | api-access, api-endpoints, data-model, charting-and-stories, integration-notes |
socceraction | 34 | SPADL format, VAEP, Expected Threat |
BeSoccer | 14 | api-access, api-endpoints |
TheSportsDB | 18 | api-access, api-endpoints, livescore, identity-surfaces |
FotMob | 3 | identity-surfaces |
Soccerdonna | 3 | identity-surfaces |
Transfermarkt | 3 | identity-surfaces |
2,295 searchable chunks across 23 providers and tools.
Impect documentation is built solely from the public ImpectAPI/open-data repository — a static Bundesliga 2023/24 snapshot, representative of Impect's structure and metric definitions rather than a complete or current mirror. Impect's commercial API is deliberately not documented here. Every enum value, KPI name and field name in
docs/impect/is validated against that repository in CI (pnpm impect:truth,src/__tests__/impect-open-data-validation.test.ts). Data source: Impect; use is subject to the repository's own Terms of Use.
Docs for AI agents are only useful if they are correct, and prose about an API is exactly the kind of thing that drifts or gets invented. Where a machine-readable source of truth exists, this repo checks the docs against it in CI rather than trusting them.
Providers | Ground truth | Checked by |
kloppy, socceraction, soccerdata, mplsoccer, floodlight, databallpy, skillcorner, fast-forward, unravelsports | The installed package itself — enum members, importable symbols, class constants, |
|
Wyscout, SkillCorner, FMDB Pro, Sportradar | The vendor's own publicly published OpenAPI spec — endpoint paths and methods |
|
BeSoccer | The vendor's published Postman collection — request vocabulary and parameters |
|
Impect | The public open-data repository |
|
Truth files live in data/provider-truth/ and are generated, not hand-written:
pnpm provider:truth # rebuild every package truth file (needs python3.11)
pnpm openapi:truth # rebuild every spec-derived truth fileThe specs those derive from are snapshots of publicly published, unauthenticated
vendor documentation. Source URLs, fetch dates and refresh instructions are in
specs/README.md. Wyscout's v3 and v4 specifications merge into
one truth file, because its docs span both. The v2 legacy specification is no
longer mirrored: the docs describe v3 and v4, and no documented fact derives from
the legacy surface.
Each package gets its own pinned venv — co-installing them makes pip silently
downgrade conflicting versions, which would produce truth that disagrees with the
docs. Bump a pin in scripts/gen_all_truth.sh and the matching version in
providers.json together, then re-run and fix whatever the tests flag.
A doc that names an enum member or importable symbol which does not exist in the
real package fails the build. scripts/gen_openapi_truth.py derives the same kind
of facts from a vendor OpenAPI spec, for providers documented that way.
Not every vocabulary is an enum. fast-forward's coordinate systems, orientations
and layouts are lowercase strings on Literal-annotated parameters, so the truth
files also record what each parameter accepts, and a doc writing
coordinates="statsbomb" fails the same way an invented enum member would.
Contributions are welcome from everyone. There are three ways to help:
Open an issue — request a new provider, flag outdated docs, or suggest a better doc source
Use the request_update tool — AI agents can flag outdated or missing docs directly via the MCP server, which queues requests locally and points to the matching public GitHub issue template
Open a PR — fix errors, add new providers, or improve existing docs
You don't need to be an expert. See CONTRIBUTING.md for the full guide.
Provider doc sources are tracked in providers.json. The crawl pipeline discovers the best doc source (llms.txt > ReadTheDocs > GitHub README) and writes markdown with provenance frontmatter.
npm run discover # probe sources without crawling
npm run crawl # crawl all providers with sources
npm run crawl -- --provider kloppy # crawl one provider
npm run ingest # rebuild search index from docs/
npm run ingest -- --provider kloppy # re-ingest one provider (incremental)Each crawled doc carries provenance metadata (source URL, source type, upstream version, crawl timestamp) that is surfaced in search results, so agents can distinguish between curated content and upstream documentation.
MIT
Compare what two or more providers offer for a specific data type or concept. For example: 'How do Opta and StatsBomb represent shot events differently?'
| Name | Required | Description | Default |
|---|---|---|---|
| topic | Yes | The concept to compare across providers. Examples: 'shot events', 'coordinate systems', 'xG', 'pass types' | |
| providers | No | Providers to compare. If omitted, compares all indexed providers. Use list_providers for indexed keys; common aliases such as ClubElo, football-data.co.uk, engsoccerdata, Sofascore, ESPN, StatsBomb Open Data, Opta F24, WhoScored, SkillCorner, Metrica, Sportec/DFL, TRACAB, Second Spectrum, SportRadar API, Soccer Extended, TheSportsDB, and TSDB are accepted. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint=true, destructiveHint=false) indicate safe read operation. The description adds context by specifying 'compare' and 'specific data type or concept', aligning with annotations. No behavioral traits like response format or limitations are disclosed, but annotations cover safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with an example, no wasted words. Efficiently communicates purpose and usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 2 parameters and no output schema. The description is minimal and lacks any mention of return format or behavior, which is a notable gap given no output schema. It is adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with descriptions for both parameters (topic and providers) including examples. The description's example ('shot events') adds minimal extra meaning; baseline 3 is appropriate as schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool compares providers for a specific data type/concept, with an example. The name 'compare_providers' aligns with this purpose, and it is distinct from sibling tools like list_providers and get_provider_docs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for comparing representations across providers via an example, but lacks explicit when-to-use or when-not-to-use guidance, such as mention of alternative tools like search_docs for finding docs. It is clear but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve documentation for a resolved provider, optionally filtered by topic or indexed category. Use after resolve_provider_id when you know which provider to inspect and want provenance-bearing docs.
| Name | Required | Description | Default |
|---|---|---|---|
| topic | No | Optional topic to search within this provider's docs. | |
| category | No | Optional indexed category to restrict results, such as api-endpoints, qualifiers, identity-surfaces, or tracking-rendering. | |
| provider | Yes | Provider key or alias. Use resolve_provider_id first when the provider name is ambiguous. | |
| max_results | No | Maximum number of provider docs to return (default 10). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false, so the description doesn't need to restate safety. The description adds 'provenance-bearing docs' implying reliability, but doesn't expand on behavior like error handling or data format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: one for core function, one for usage context. No wasted words. Front-loaded with the action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, usage order, and filtering. No output schema exists, but the description doesn't explain return format. However, for a straightforward retrieval tool with good annotations, it is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for each parameter. The description reiterates filtering options (topic, category) and emphasizes 'resolved provider,' adding context but not compensating for low coverage since coverage is already high.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'retrieve' and resource 'provider docs', specifying filtering by topic or category. It distinguishes from siblings by mentioning 'resolved provider' and referencing resolve_provider_id as a prerequisite.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use after resolve_provider_id when you know which provider to inspect and want provenance-bearing docs.' This gives a clear usage context and prerequisite. It does not explicitly state when not to use, but the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all indexed football data providers, their document count, and coverage categories. Use to understand what documentation is available. Call this first to see what providers are indexed before searching.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. Description adds that it lists providers and their metadata, which is consistent and sufficient. No additional behavioral traits needed beyond what's disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, both front-loaded with purpose and usage. Every word earns its place with no redundancy or filler. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters, no output schema, and a simple list operation, the description fully covers what the tool does and how to use it. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters defined (0 params), so baseline is 4 per scoring guidelines. Description does not need to add param info since schema coverage is 100% and there is nothing to describe.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'List' and clearly identifies resource as 'all indexed football data providers' with included attributes (document count, coverage categories). This distinguishes it from sibling tools like search_docs and get_provider_docs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'Use to understand what documentation is available. Call this first to see what providers are indexed before searching.' This provides clear context and implies alternatives (e.g., search_docs for searching).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Request that a provider's documentation be added, updated, or recrawled. Use when you notice docs are outdated, a provider is missing, or you know of a better documentation source. Requests are queued for review.
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | Type of request: new_provider (add a new tool/library), recrawl (refresh existing docs), flag_outdated (mark docs as stale), suggest_source (recommend a better doc source like llms.txt) | |
| reason | Yes | Why this update is needed. Be specific: version bump, missing event types, new API endpoints, etc. | |
| provider | Yes | Provider name (existing or proposed). Examples: 'statsbomb', 'mplsoccer', 'floodlight' | |
| suggested_urls | No | URLs for documentation sources (readthedocs, GitHub, llms.txt, etc.) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate non-read-only and non-destructive. Description adds that it's a queued request, not an immediate modification, which is crucial behavioral context. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each purposeful: states action, gives usage context, and adds behavioral note. No unnecessary words, front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (4 params, no output schema), the description covers purpose, usage scenarios, and queuing behavior. Lacks detail on return value or confirmation, but sufficient for agent decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% coverage with clear descriptions for each parameter. The description does not add new parameter information beyond what the schema provides, meeting baseline but not exceeding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Request' and the resource 'provider's documentation', specifying actions (add, update, recrawl). It distinguishes from sibling tools like get_provider_docs or search_docs which are read-only.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'when you notice docs are outdated, a provider is missing, or you know of a better documentation source.' It also notes requests are queued, implying delayed action. Missing explicit when-not-to-use or alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve a football entity (player, team, or coach) to get cross-provider IDs. Use when you need to map between Transfermarkt, FBref, Sofascore, Opta, and other provider IDs, or when you need to look up a player/team/coach by name.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | ID from the source provider to resolve to all other IDs | |
| qid | No | Wikidata QID for direct lookup (e.g. 'Q99760796') | |
| name | No | Entity name to search for (e.g. 'Cole Palmer', 'Arsenal'). Fuzzy match on name and aliases. | |
| type | No | Filter results by entity type | |
| provider | No | Source provider for ID resolution (e.g. 'transfermarkt', 'fbref', 'sofascore', 'opta', 'soccerway') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, and destructiveHint. The description adds value by mentioning fuzzy match on name and aliases, and cross-provider resolution. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose, followed by usage example. Every word contributes meaning. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description mentions the result (cross-provider IDs) and entity types. It lacks details on return format or pagination, but the complexity is moderate and annotations fill gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with good descriptions. The tool description reiterates the purpose of name and provider but does not add significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('resolve'), resource ('football entity'), and outcome ('cross-provider IDs'). It distinguishes from siblings by specifying the mapping use case and listing providers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use: 'when you need to map between...' and 'when you need to look up...'. It does not provide explicit exclusion scenarios or directly reference alternatives like compare_providers, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve a football data provider name or alias to the canonical football-docs provider key before searching. Use when users mention brands, vendors, products, or aliases such as Stats Perform, Opta F24, Hudl Wyscout, Second Spectrum, FMDB, Transfer Room, FBref, Sofascore, or TheSportsDB.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Provider name, brand, product, or alias to resolve to a canonical provider key. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's additional behavioral context is minimal. It adds that resolution maps to a canonical key, which is consistent. No contradictions, but no extra behavioral details like error handling or idempotency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first states the action concisely, second lists usage examples. No wasted words. Front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one param, no output schema, read-only), the description fully covers what an agent needs: purpose, when to use, and input examples. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema description already defines the query parameter. The tool description adds concrete examples (e.g., Stats Perform, Opta F24) that help clarify acceptable input values, enhancing semantic understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: resolving a provider name/alias to a canonical key. It specifies the verb 'resolve', the resource (provider name to key), and lists numerous examples, leaving no ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use when users mention brands, vendors, products, or aliases' with specific examples. Implies it's a preprocessing step for searching. Lacks explicit exclusion criteria but provides clear guidance on when to invoke.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search football data provider documentation. Use for finding event types, qualifier IDs, API endpoints, coordinate systems, data models, and cross-provider mappings. Returns the most relevant documentation chunks.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query. Examples: 'Opta goal qualifier', 'StatsBomb shot event type', 'coordinate system differences', 'xG qualifier ID', 'SportMonks fixture endpoint', 'FMDB Pro players endpoint' | |
| provider | No | Optional provider filter. Use list_providers for indexed provider keys. Common aliases such as fbref, understat, ClubElo, football-data.co.uk, engsoccerdata, Sofascore, ESPN, FMDB, TransferRoom, Hudl Wyscout, Stats Perform, Opta F24, WhoScored, Metrica, Sportec/DFL, TRACAB, Second Spectrum, SportRadar API, Soccer Extended, TheSportsDB, and TSDB are accepted. | |
| max_results | No | Maximum number of results to return (default 10) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds that it returns 'most relevant documentation chunks,' implying ranking but not elaborating on how results are ordered or paginated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (three sentences), front-loaded with the main purpose, and each sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose, scope (football data provider docs), and output (chunks). It is adequate given the presence of annotations and full schema, though it could mention that search spans all indexed providers.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed parameter descriptions including examples. The tool description does not add further meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it searches 'football data provider documentation' and lists specific use cases (event types, qualifier IDs, etc.). This distinguishes it from sibling tools like get_provider_docs (retrieval) and list_providers (listing).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use for finding...' which provides clear when-to-use context. However, it does not mention when not to use it or point to alternative sibling tools like get_provider_docs for full documentation access.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool has a clearly distinct purpose: listing providers, searching docs, comparing providers, resolving entities and IDs, retrieving provider docs, and requesting updates. No overlap in functionality.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., list_providers, resolve_entity, search_docs), making them predictable.
With 7 tools, the set is well-scoped for the domain of football data documentation, covering all essential operations without being excessive.
The tool surface covers listing, searching, comparing, resolving entities and provider IDs, and updating docs. No obvious gaps for the intended use case of exploring football data providers.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Versioned documentation registry and semantic search for AI tools and coding assistants.
Football fixtures, standings, and odds intelligence for AI agents.
Provide your AI coding tools with token-efficient access to up-to-date technical documentation for…
Public social-data API and live docs for AI coding agents.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/withqwerty/football-docs'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
