Football Database and Results

Match results archive

search_results

Read-onlyIdempotent

[FREE for the last 7 days · PAID for the archive] Search the match archive: finished matches, newest first, with scores.

This is the raw history behind every other tool — decades of results across national team football, domestic leagues and cups. Filter by team, competition, single season, outcome (home win, away win or draw) and date range, in any combination: "Arsenal's draws since 2020", "every match in the 2025/26 Premier League", "all draws in the World Cup". Each match returns its date, competition and edition, both teams, the score and whether it was a draw.

Results are paginated, 50 per page by default; page walks through them and meta.total tells you how many matches matched before you start.

Free, no key needed, for recent results: the first page of 50, and any from date inside the last 7 days. Reaching further back — an older from, a bigger limit, or page 2 onward — is the archive and costs 1 point per call (1 point = 1 cent), one point per page.

Input Schema

TableJSON Schema

Name	Required	Description
`to`	No	Latest match date, inclusive, as YYYY-MM-DD.
`from`	No	Earliest match date, inclusive, as YYYY-MM-DD. Inside the last 7 days the call is free and needs no key; earlier than that it costs 1 point.
`page`	No	Page number, from 1. Page 1 can be free; every page after it is a separate call and costs its own point.
`type`	No	Restrict to national-team or club football.
`limit`	No	Page size: 50, 100, 250 or 500. Default 50, which is also the largest free page. Anything else is treated as 100.
`outcome`	No	H for a home win, A for an away win, D for a draw.
`team_id`	No	Matches involving this team, home or away. Numeric id from list_teams.
`competition_id`	No	Restrict to one competition. Id from list_tournaments.
`competition_item_id`	No	Restrict to a single edition or season. Edition ids come from list_tournaments with a `tournament` argument.

Output Schema

TableJSON Schema

Name	Required	Description
`data`	Yes	Matches, newest first.
`meta`	No	Pagination: which page this is and how many rows exist.
`links`	No	first/last/prev/next page URLs on the REST API.

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedSep 30, 2026

addedOutput schema / properties / data / items / properties / ninety_score_unknown

Added value: +{
+  "description": "Played extra-time match known to be level at ninety minutes, with the exact ninety-minute score unavailable.",
+  "type": "boolean"
+}

changedOutput schema / properties / data / items / properties / score / description

Previous value: -"Final score; both null until the match is played."New value: +"Ninety-minute score; both values null before play or when the exact score is unknown, including played extra-time draws."

addedOutput schema / properties / data / items / properties / score_120

Added value: +{
+  "description": "Score after extra time; both values null when unavailable or no extra time was played.",
+  "properties": {
+    "away": {
+      "type": [
+        "integer",
+        "null"
+      ]
+    },
+    "home": {
+      "type": [
+        "integer",
+        "null"
+      ]
+    }
+  },
+  "type": "object"
+}

Changed1 schema field changedSep 23, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "data": {
+      "description": "Matches, newest first.",
+      "items": {
+        "description": "A match.",
+        "properties": {
+          "away_team": {
+            "description": "A team reference.",
+            "properties": {
+              "id": {
+                "description": "Team id — the argument every team tool takes.",
+                "type": "integer"
+              },
+              "name": {
+                "description": "Short display name.",
+                "type": "string"
+              },
+              "slug": {
+                "description": "URL slug; accepted anywhere an id is.",
+                "type": "string"
+              }
+            },
+            "required": [
+              "id",
+              "slug",
+              "name"
+            ],
+            "type": "object"
+          },
+          "competition": {
+            "description": "The competition and edition the match belongs to.",
+            "properties": {
+              "edition": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "edition_id": {
+                "description": "The season or edition id, from list_tournaments.",
+                "type": [
+                  "integer",
+                  "null"
+                ]
+              },
+              "id": {
+                "type": "integer"
+              },
+              "name": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "year": {
+                "type": [
+                  "integer",
+                  "null"
+                ]
+              }
+            },
+            "type": [
+              "object",
+              "null"
+            ]
+          },
+          "date": {
+            "description": "Match date, YYYY-MM-DD.",
+            "type": "string"
+          },
+          "home_team": {
+            "description": "A team reference.",
+            "properties": {
+              "id": {
+                "description": "Team id — the argument every team tool takes.",
+                "type": "integer"
+              },
+              "name": {
+                "description": "Short display name.",
+                "type": "string"
+              },
+              "slug": {
+                "description": "URL slug; accepted anywhere an id is.",
+                "type": "string"
+              }
+            },
+            "required": [
+              "id",
+              "slug",
+              "name"
+            ],
+            "type": "object"
+          },
+          "id": {
+            "description": "Match id, as get_draw_model takes it.",
+            "type": "integer"
+          },
+          "is_draw": {
+            "description": "Whether the match ended level.",
+            "type": "boolean"
+          },
+          "result": {
+            "description": "H home win, A away win, D draw; empty until played.",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "score": {
+            "description": "Final score; both null until the match is played.",
+            "properties": {
+              "away": {
+                "type": [
+                  "integer",
+                  "null"
+                ]
+              },
+              "home": {
+                "type": [
+                  "integer",
+                  "null"
+                ]
+              }
+            },
+            "type": "object"
+          },
+          "status": {
+            "description": "PLAYED, SCHEDULED, POSTPONED and so on.",
+            "type": "string"
+          }
+        },
+        "required": [
+          "id",
+          "date"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "links": {
+      "description": "first/last/prev/next page URLs on the REST API.",
+      "type": "object"
+    },
+    "meta": {
+      "description": "Pagination: which page this is and how many rows exist.",
+      "properties": {
+        "current_page": {
+          "type": "integer"
+        },
+        "last_page": {
+          "type": "integer"
+        },
+        "per_page": {
+          "type": "integer"
+        },
+        "total": {
+          "description": "Rows across every page.",
+          "type": "integer"
+        }
+      },
+      "type": "object"
+    }
+  },
+  "required": [
+    "data"
+  ],
+  "type": "object"
+}

First observedSep 22, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations only declare readOnly/idempotent; the description adds substantial behavior the annotations cannot: the pricing model (free first page/last 7 days, 1 point per archive page), pagination default of 50, and how `meta.total` works. This is exactly the cost/auth context the annotation bar leaves open.

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?

Front-loads the free/paid summary in brackets, then elaborates filtering, returns, and pagination in tight paragraphs. Slightly long but every section carries distinct information; no 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 9 optional params and an output schema present, the description still covers filtering combinations, pagination, return shape, and the full free/paid boundary. An agent has everything needed to scope a call and predict its cost.

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 baseline is 3. The description adds cross-parameter semantics the schema only partially captures — that going beyond the last 7 days, raising `limit` past 50, or moving past page 1 each trigger a charge — tying individual params to the cost model.

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?

States a specific verb and resource ('Search the match archive') with scope ('finished matches, newest first, with scores') and positions itself as 'the raw history behind every other tool.' An agent can distinguish this history-search tool from siblings like head_to_head or get_team_streaks without opening a schema.

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?

Gives concrete usage context and worked filter examples ('Arsenal's draws since 2020'), plus explicit when-free vs when-paid conditions. It does not name which sibling to use for narrower questions, so it stops short of full alternative routing.

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?