Football Data

Get Competition Matches

get_competition_matches

Read-onlyIdempotent

Fixtures and results for a competition — Premier League, Championship, Primera División/La Liga, Serie A, Bundesliga, Ligue 1, Eredivisie, Primeira Liga, Brasileirão, Copa Libertadores, UEFA Champions League, European Championship, or the World Cup (see competition codes below). Filter by status (SCHEDULED, LIVE, IN_PLAY, PAUSED, FINISHED, POSTPONED, SUSPENDED, CANCELLED), date range, matchday, stage, or season year. "Next round" / "upcoming fixtures" questions: pass no status or status: "SCHEDULED", not a matchday number, unless the caller already knows which matchday number it is.

Input Schema

Name	Required	Description
`stage`	No	Stage (e.g., "GROUP_STAGE", "QUARTER_FINALS")
`season`	No	Season start year (e.g., 2025)
`status`	No	Match status filter (SCHEDULED \| LIVE \| IN_PLAY \| PAUSED \| FINISHED \| POSTPONED \| SUSPENDED \| CANCELLED)
`date_to`	No	YYYY-MM-DD
`matchday`	No	Round number
`date_from`	No	YYYY-MM-DD
`competition`	Yes	Competition code (e.g., "PL" = Premier League, "PD" = La Liga, "CL" = Champions League)

Output Schema

Name	Required	Description
`count`	Yes	Number of matches returned
`matches`	Yes
`competition`	Yes	Competition code used in the query

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedMay 22, 2026

addedInput schema / examples

Added value: +[
+  {
+    "competition": "PL"
+  },
+  {
+    "competition": "CL",
+    "season": 2024,
+    "status": "FINISHED"
+  }
+]

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "competition": {
+      "description": "Competition code used in the query",
+      "type": "string"
+    },
+    "count": {
+      "description": "Number of matches returned",
+      "type": "number"
+    },
+    "matches": {
+      "items": {
+        "properties": {
+          "away": {
+            "description": "Away team name",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "away_id": {
+            "description": "Away team ID",
+            "type": [
+              "number",
+              "null"
+            ]
+          },
+          "competition": {
+            "description": "Competition name",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "competition_code": {
+            "description": "Competition code",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "group": {
+            "description": "Group name if applicable",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "home": {
+            "description": "Home team name",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "home_id": {
+            "description": "Home team ID",
+            "type": [
+              "number",
+              "null"
+            ]
+          },
+          "id": {
+            "description": "Match ID",
+            "type": [
+              "number",
+              "null"
+            ]
+          },
+          "matchday": {
+            "description": "Round/matchday number",
+            "type": [
+              "number",
+              "null"
+            ]
+          },
+          "score_full_time": {
+            "description": "Full-time score (e.g., '2-1' or '-' if not final)",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "score_half_time": {
+            "description": "Half-time score (e.g., '1-0' or '-' if not played)",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "stage": {
+            "description": "Competition stage (e.g., GROUP_STAGE)",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "status": {
+            "description": "Match status",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "utc_date": {
+            "description": "Match date/time in UTC (ISO 8601)",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "venue": {
+            "description": "Venue name",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "winner": {
+            "description": "Winner ('HOME', 'AWAY', 'DRAW', or null)",
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "competition",
+    "count",
+    "matches"
+  ],
+  "type": "object"
+}

First observedMay 12, 2026

TDQS

A3.9/5.0

Behavior3/5

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

Annotations already declare readOnly, idempotent, openWorld, non-destructive, so the safety profile is covered. The description adds nothing beyond that about result volume, pagination, or freshness of live scores. The parenthetical "see `competition` codes below" defers to the schema rather than disclosing anything itself.

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?

Two sentences, both front-loaded with the actionable material: scope first, then filtering and the matchday pitfall. The competition list is long but directly functional since codes must be inferred from names.

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?

With an output schema present, return values need not be described, and the filter guidance covers the highest-risk invocation error. What is missing is whether matchday applies uniformly across cup competitions, which would matter for CL/World Cup calls.

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, but the description earns above baseline by explaining the interaction between `status` and `matchday` for upcoming-fixture queries and by naming valid status values in context of filtering. It still leaves `stage` and `season` semantics to the schema.

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

Purpose4/5

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

States a specific verb-and-resource pairing ("Fixtures and results for a competition") and enumerates the covered competitions, which lets an agent distinguish it from get_team_matches by scope. It stops short of explicitly naming the sibling, so differentiation is inferential rather than stated.

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 routing guidance for the common ambiguous case: "Next round"/"upcoming fixtures" queries should pass no status or SCHEDULED rather than a matchday number. It also lists the available filter axes. It does not tell the caller when to prefer get_team_matches or get_competition_standings instead.

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

All Football Data 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.