Football Database and Results

Competitions and seasons

list_tournaments

Read-onlyIdempotent

[FREE] Every competition covered — leagues, domestic cups, continental cups, World Cups — with how many matches and how many draws each one holds.

Two uses. Without tournament it answers "what is in this database, and how draw-heavy is each competition?", returning each competition's id, slug, country, match count, draw count and draw percentage. With tournament (an id or slug) it returns that one competition in full: the years it covers, every edition newest first with its champion where one was decided, and the all-time winners ranking with title counts and years.

The competition ids here are what search_results and head_to_head filter by.

Free: no key needed, and it costs a key holder nothing either.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`limit`	No	How many competitions to list. Default 25; the total is always reported.
`tournament`	No	One competition, by numeric id or slug (53 or "norway-cup"). Returns its editions, champions and all-time winners instead of the list.

Output Schema

TableJSON Schema

Name	Required	Description
`data`	Yes	Competitions, or one competition's editions.
`hint`	No	Present only when rows were left out: how to narrow the call.
`total`	Yes	How many rows matched before the limit.
`returned`	Yes	How many rows are in data.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedSep 23, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "data": {
+      "description": "Competitions, or one competition's editions.",
+      "items": {
+        "description": "A competition, or with `tournament` given, one of its editions.",
+        "properties": {
+          "country": {
+            "description": "The country a team or competition belongs to.",
+            "properties": {
+              "fifa_code": {
+                "description": "Three-letter FIFA code.",
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "id": {
+                "type": "integer"
+              },
+              "name": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              }
+            },
+            "required": [
+              "id"
+            ],
+            "type": [
+              "object",
+              "null"
+            ]
+          },
+          "draw_percent": {
+            "type": [
+              "number",
+              "null"
+            ]
+          },
+          "draws_count": {
+            "type": [
+              "integer",
+              "null"
+            ]
+          },
+          "id": {
+            "type": "integer"
+          },
+          "matches_count": {
+            "type": [
+              "integer",
+              "null"
+            ]
+          },
+          "name": {
+            "type": "string"
+          },
+          "slug": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "type": {
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        },
+        "required": [
+          "id",
+          "name"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "hint": {
+      "description": "Present only when rows were left out: how to narrow the call.",
+      "type": "string"
+    },
+    "returned": {
+      "description": "How many rows are in data.",
+      "type": "integer"
+    },
+    "total": {
+      "description": "How many rows matched before the limit.",
+      "type": "integer"
+    }
+  },
+  "required": [
+    "data",
+    "total",
+    "returned"
+  ],
+  "type": "object"
+}

First observedSep 22, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Beyond the read-only and idempotent annotations, the description adds substantial behavioral detail: it reports draw percentage, orders editions newest first, includes champions only where decided, reports the total even when limited, and states the tool is free and costs a key holder nothing. No contradiction with annotations exists.

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

Conciseness5/5

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

The description is front-loaded with the core purpose and free status, then organized into two clear usage modes, then the cross-tool linkage. Every sentence adds useful information, and the structure makes it easy for an agent to extract the behavior without wading through filler.

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

Completeness5/5

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

With a rich input schema and an output schema present, the description covers what an agent needs: the two modes, exactly what each returns, how limits behave, and how the ids relate to sibling tools. No major operational or selection detail is missing.

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 coverage is 100%, so the baseline is 3, but the description adds meaningful semantics: `tournament` toggles between a list and a single-competition detail view, and `limit` controls only the competitions list while the total is always reported. This goes beyond the schema's already informative parameter descriptions.

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 states a specific verb and resource: listing every competition covered, with league, cup, and World Cup scoping, plus per-competition match and draw counts. It also differentiates the two modes (with and without `tournament`) and explicitly ties competition ids to `search_results` and `head_to_head`, distinguishing it from sibling tools.

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?

The description clearly tells an agent when to use it: to discover what competitions are in the database and how draw-heavy they are, or to pull a single competition's full season/champion history. It also explains that ids from this tool are what `search_results` and `head_to_head` filter by, giving practical routing guidance, though it does not explicitly state when not to use it.

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

All Football Database and Results tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?