footballcharts-mcp

Team page

get_team

Read-onlyIdempotent

Everything held on one team in one league season: its table row (with luck and expected points), the full match log (date, opponent, venue H/A, score, half-time score, first-goal minute, outcome), goals per 15-minute bin, first-goal distribution, season match-stat averages where the league is covered (shots, shots on target, shots against, possession, corners, xG for/against — null when not held), and the seasons available. team is a slug: lower-case, spaces as hyphens, e.g. 'arsenal', 'manchester-city'. Take the exact name from get_league_table first when unsure. Use for one team in depth ("tell me about Arsenal's season"). Use get_league_table for every team shallowly, get_results with a team filter for just the scores, get_goal_timing to compare timing across the whole league. Example: "How is Arsenal doing?" → get_team premier, team="arsenal".

Input Schema

TableJSON Schema

Name	Required	Description
`team`	Yes	Team slug, e.g. 'arsenal', 'manchester-city' (from the table's team names, lower-case, spaces as hyphens)
`league`	Yes	League key from list_leagues, e.g. 'premier' (England), 'spain1', 'brazil1', 'sweden1', 'wgermany1' (women). Not the display name.
`season`	No	Season string exactly as list_leagues returns it: winter-calendar leagues look like '2026-2027', summer-calendar leagues (Brazil, Sweden, Norway, Japan…) like '2026'. Omit for the current season. The free tier serves the current and previous season only.

Output Schema

TableJSON Schema

Name	Required	Description
`slug`	No
`team`	No
`stats`	No	Per-match averages over this season, computed from stored match statistics; null where the league has none
`league`	No
`season`	No
`matches`	No
`ranking`	No	The team's table row
`seasons`	No
`attribution`	No	Cite as "Data by football-charts.com"
`first_goal_bins`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedSep 16, 2026

addedOutput schema / properties / stats

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": true,
+      "properties": {
+        "corners_avg": {
+          "$ref": "#/properties/ranking/anyOf/0/properties/avg_goals_scored"
+        },
+        "matches_with_stats": {
+          "$ref": "#/properties/ranking/anyOf/0/properties/position"
+        },
+        "possession_avg": {
+          "$ref": "#/properties/ranking/anyOf/0/properties/avg_goals_scored"
+        },
+        "shots_against_avg": {
+          "$ref": "#/properties/ranking/anyOf/0/properties/avg_goals_scored"
+        },
+        "shots_avg": {
+          "$ref": "#/properties/ranking/anyOf/0/properties/avg_goals_scored"
+        },
+        "shots_on_target_avg": {
+          "$ref": "#/properties/ranking/anyOf/0/properties/avg_goals_scored"
+        },
+        "xg_against_avg": {
+          "$ref": "#/properties/ranking/anyOf/0/properties/avg_goals_scored"
+        },
+        "xg_avg": {
+          "$ref": "#/properties/ranking/anyOf/0/properties/avg_goals_scored"
+        }
+      },
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Per-match averages over this season, computed from stored match statistics; null where the league has none"
+}

Changed1 schema field changedSep 6, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": true,
+  "properties": {
+    "attribution": {
+      "description": "Cite as \"Data by football-charts.com\"",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "first_goal_bins": {
+      "anyOf": [
+        {
+          "items": {
+            "additionalProperties": true,
+            "properties": {
+              "count": {
+                "$ref": "#/properties/ranking/anyOf/0/properties/position"
+              },
+              "time": {
+                "$ref": "#/properties/team"
+              }
+            },
+            "type": "object"
+          },
+          "type": "array"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "league": {
+      "$ref": "#/properties/team"
+    },
+    "matches": {
+      "anyOf": [
+        {
+          "items": {
+            "additionalProperties": true,
+            "properties": {
+              "away": {
+                "$ref": "#/properties/team"
+              },
+              "date": {
+                "$ref": "#/properties/team"
+              },
+              "first_goal_time": {
+                "$ref": "#/properties/team"
+              },
+              "home": {
+                "$ref": "#/properties/team"
+              },
+              "ht": {
+                "$ref": "#/properties/team"
+              },
+              "outcome": {
+                "$ref": "#/properties/team",
+                "description": "'W' | 'D' | 'L'"
+              },
+              "score": {
+                "$ref": "#/properties/team"
+              },
+              "time": {
+                "$ref": "#/properties/team"
+              },
+              "venue": {
+                "$ref": "#/properties/team",
+                "description": "'H' or 'A'"
+              }
+            },
+            "type": "object"
+          },
+          "type": "array"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "ranking": {
+      "anyOf": [
+        {
+          "additionalProperties": true,
+          "properties": {
+            "avg_goals_conceded": {
+              "$ref": "#/properties/ranking/anyOf/0/properties/avg_goals_scored"
+            },
+            "avg_goals_scored": {
+              "$ref": "#/properties/ranking/anyOf/0/properties/expected_points"
+            },
+            "clean_sheets": {
+              "$ref": "#/properties/ranking/anyOf/0/properties/position"
+            },
+            "drawn": {
+              "$ref": "#/properties/ranking/anyOf/0/properties/position"
+            },
+            "expected_points": {
+              "description": "Points the underlying numbers say the team should have"
+            },
+            "expected_position": {
+              "$ref": "#/properties/ranking/anyOf/0/properties/position"
+            },
+            "goal_difference": {
+              "$ref": "#/properties/ranking/anyOf/0/properties/position"
+            },
+            "goals_against": {
+              "$ref": "#/properties/ranking/anyOf/0/properties/position"
+            },
+            "goals_for": {
+              "$ref": "#/properties/ranking/anyOf/0/properties/position"
+            },
+            "last_5_form": {
+              "$ref": "#/properties/team",
+              "description": "Latest results as letters, e.g. 'WWDLW'"
+            },
+            "last_5_points": {
+              "$ref": "#/properties/ranking/anyOf/0/properties/position"
+            },
+            "lost": {
+              "$ref": "#/properties/ranking/anyOf/0/properties/position"
+            },
+            "luck_category": {
+              "$ref": "#/properties/team",
+              "description": "'lucky' | 'fair' | 'unlucky'"
+            },
+            "luck_difference": {
+              "$ref": "#/properties/ranking/anyOf/0/properties/expected_points",
+              "description": "points − expected_points; positive = ahead of the numbers"
+            },
+            "over_25_percentage": {
+              "$ref": "#/properties/ranking/anyOf/0/properties/avg_goals_scored"
+            },
+            "played": {
+              "$ref": "#/properties/ranking/anyOf/0/properties/position"
+            },
+            "points": {
+              "$ref": "#/properties/ranking/anyOf/0/properties/position"
+            },
+            "position": {},
+            "team": {
+              "type": "string"
+            },
+            "won": {
+              "$ref": "#/properties/ranking/anyOf/0/properties/position"
+            }
+          },
+          "required": [
+            "team"
+          ],
+          "type": "object"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "The team's table row"
+    },
+    "season": {
+      "$ref": "#/properties/team"
+    },
+    "seasons": {
+      "anyOf": [
+        {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "slug": {
+      "$ref": "#/properties/team"
+    },
+    "team": {}
+  },
+  "type": "object"
+}

First observedSep 6, 2026

TDQS

A4.7/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds value beyond that: it discloses that stats are null when not held, explains the slug format ('take the exact name from get_league_table first when unsure'), and notes the free-tier limitation (current and previous season only). All of this contextualizes behavior without contradicting any annotation.

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?

The description is a bit long but everything earns its place: the opening sentence lists the output scope, then it covers slug format, season mechanics, usage alternatives, and a working example. It is front-loaded with the core purpose and the alternatives appear early in the flow. Slight redundancy ('Everything held on one team' followed by specifics) but not wasteful enough to drop below a 4.

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?

Given the tool returns a rich payload and has an output schema (so return values need not be restated), the description is comprehensive: it covers edge cases (null stats), input derivation (exact team name), season format nuances, and free-tier availability. It also routes to alternatives so an agent can choose correctly. Nothing critical is missing for safe, accurate invocation.

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

Parameters5/5

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

Although schema coverage is 100%, the description enriches parameter understanding materially. For 'team' it specifies the slug format (lower-case, spaces as hyphens) and tells the agent to pull the exact name from get_league_table. For 'season' it explains winter vs summer calendar formats, when to omit it, and the free-tier restriction. These are not in the schema and prevent mis-invocation.

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 resource ('one team in one league season') and enumerates the data fields returned (table row, match log, goals per bin, etc.), which is far beyond a tautology. It also explicitly distinguishes itself from siblings by naming get_league_table, get_results, and get_goal_timing, so an agent can tell exactly what this tool covers.

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

Usage Guidelines5/5

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

It gives explicit when-to-use guidance ('Use for one team in depth') and names the alternatives with their exact purposes ('get_league_table for every team shallowly', 'get_results with a team filter for just the scores', 'get_goal_timing to compare timing across the whole league'). A concrete example ('How is Arsenal doing?' → get_team premier, team='arsenal') ties it together.

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

All footballcharts-mcp 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.