# Head-to-Head Record Calculator AI Agent Connect

> Head-to-Head Record Calculator MCP gives your AI client direct access to professional football performance data. It calculates wins, losses, draws, and scoring efficiency between specific teams. Instead of guessing, your agent can pull exact match histories and dominance ratios to provide accurate sports analysis.

## Overview
- **Category:** statistics
- **Price:** Free
- **Endpoint:** https://edge.vinkius.com/vk_preview_BIl4WgcKSZk9WbMwEydrCIOuhHdMevPAvesLjdNR/ai-agent-connect
- **Tags:** football, soccer, statistics, h2h, sports-data

## Description

You can stop manually searching for old match results. This MCP gives your AI client the ability to pull exact head-to-head statistics between any two football teams. It follows professional standards, meaning it won't mess up your data by counting penalty shootout goals in the total goal counts. 

Your agent can look up a complete statistical overview of how teams match up, or it can dig into specific match histories to see exactly how a game played out. If you need to know which team actually dominates, the MCP calculates efficiency ratios like win percentages and scoring rates. You can even see how these records are distributed across different leagues. It's built for anyone who needs hard numbers rather than general trends.

## Tools

### query_competition_breakdown
This tool shows how head-to-head records are distributed across different competitions.

### query_h2h_summary
This tool provides a statistical overview of how two specific teams have performed against each other.

### query_match_history
This tool retrieves the individual match results used to build the head-to-head record.

### query_team_comparison_efficiency
This tool calculates efficiency ratios to show how much one team dominates another.

## Prompt Examples

**Prompt:** 
```
What is the head-to-head record between Team A and Team B?
```

**Response:** 
```
In their historical matchups, Team A has 3 wins, Team B has 1 win, and they have had 2 draws. Team A has scored 8 goals while Team B has scored 4 goals.
```

**Prompt:** 
```
Show me the match history between these two teams in the Premier League.
```

**Response:** 
```
The matches in the Premier League between these teams are: 2023-05-12 (2-1), 2022-11-05 (1-1), and 2021-08-20 (0-2).
```

**Prompt:** 
```
How dominant is Team A compared to Team B?
```

**Response:** 
```
Team A has a 60% win percentage, an average goal scoring rate of 1.5 goals per match, and a clean sheet rate of 33% against Team B.
```

## Capabilities

### Matchup Summaries
Your agent pulls total wins, draws, and losses for specific team pairings.

### Granular Match Logs
The AI retrieves specific dates and scores for individual historical games.

### Dominance Metrics
Your agent calculates win percentages and scoring rates to compare team efficiency.

### League Distribution
The AI breaks down how H2H records vary across different competitions.

### Standardized Scoring
The tool excludes penalty shootout goals to keep goal counts professional.

## Use Cases

### Pre-Match Analysis
Your agent compares historical win rates to predict how a matchup might go.

### Content Drafting
You pull specific match histories to add depth to sports articles.

### Efficiency Benchmarking
Compare how one team's scoring rate stacks up against a specific opponent.

### League Contextualization
See how a rivalry performs in different leagues or competitions.

## Benefits

- Eliminates manual searching for historical match scores.
- Provides standardized goal counts that exclude penalty shootouts.
- Calculates dominance ratios automatically for your agent.
- Delivers competition-specific breakdowns of team records.

## How It Works

Connect your client to Vinkius and start querying football data immediately.

1. Connect your MCP-compatible client to the Vinkius platform.
2. Ask your AI agent for specific head-to-head stats or match histories.
3. The MCP executes the requested query against the football database.
4. Your agent receives the precise data and presents it to you.

## Frequently Asked Questions

**Does this MCP include penalty shootout goals?**
No. The calculations follow professional standards and exclude penalty shootout goals from total goal counts.

**How do I use this with Claude or Cursor?**
You connect your client to Vinkius once, and the MCP becomes available to your agent in those environments.

**Can I see individual match scores?**
Yes. You can use the match history tool to get specific dates and scores for past games.

**What kind of efficiency metrics are provided?**
The MCP calculates win percentages, scoring rates, and other ratios to show team dominance.

**Can I filter stats by specific leagues?**
Yes. The competition breakdown tool allows you to see how records are distributed across different leagues.

**How are penalty shootouts handled in the statistics?**
Goals scored during penalty shootouts are excluded from the 'Goals For' and 'Goals Against' totals. The match result is recorded based on regulation time, but the shootout winner is used to determine the final win/loss and points.

**Can I filter matches by a specific competition?**
Yes, you can use the `competitionId` filter in tools like `query_h2h_summary` or `query_match_history` to restrict results to a specific league or tournament.

**How are points calculated for team comparisons?**
The engine uses the standard competitive scoring system: 3 points for a win, 1 point for a draw, and 0 points for a loss.