# College Football Data

CollegeFootballData.com provides comprehensive college football data, including game scores, statistics, and recruiting information, accessible via a RESTful API.

- **Category:** analytics
- **Auth:** API_KEY
- **Composio Managed App Available?** N/A
- **Tools:** 56
- **Triggers:** 0
- **Slug:** `COLLEGE_FOOTBALL_DATA`
- **Version:** 20260319_00

## Tools

### Advanced Box Score

**Slug:** `COLLEGE_FOOTBALL_DATA_ADVANCED_BOX_SCORE`

Retrieves advanced analytics for a single college football game including: - Team metrics: PPA (Predicted Points Added), success rates, rushing efficiency, havoc rates, scoring opportunities - Player metrics: Usage rates by quarter and play type, individual PPA breakdowns - Game info: Teams, scores, win probabilities, excitement index Requires a valid gameId from Get Games and Results action. Returns detailed breakdown by quarter.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `gameId` | integer | Yes | Unique game identifier from CFBD API. Obtain from Get Games and Results action. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Advanced Game Stats

**Slug:** `COLLEGE_FOOTBALL_DATA_ADVANCED_GAME_STATS`

Tool to retrieve advanced team metrics at the game level. Use when detailed offensive and defensive metrics (success rates, explosiveness, havoc) are needed.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team` | string | No | Team filter by school name (e.g., 'Alabama', 'Ohio State'). Required if year is not specified. |
| `week` | integer | No | Week number to filter games (e.g., 1–18). |
| `year` | integer | No | Season year to filter games (e.g., 2023). Required if team is not specified. |
| `opponent` | string | No | Opponent filter by school name (e.g., 'Clemson'). |
| `seasonType` | string ("regular" | "postseason" | "both") | No | Season type filter: 'regular', 'postseason', or 'both'. Defaults to 'regular' if not specified. |
| `excludeGarbageTime` | boolean | No | If true, exclude garbage time plays from calculations. Useful for more accurate metrics. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Advanced Season Stats by Team

**Slug:** `COLLEGE_FOOTBALL_DATA_ADVANCED_SEASON_STATS_TEAM`

Retrieve advanced season-level team statistics including PPA (Predicted Points Added), success rates, explosiveness, havoc metrics, and rushing/passing efficiency breakdowns. Use this for in-depth team performance analysis beyond basic stats. At least one of 'year' or 'team' must be provided.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team` | string | No | Team name filter (e.g., 'Alabama', 'Ohio State'). Required if 'year' is not specified. Use full school name. |
| `year` | integer | No | Season year to retrieve stats for (e.g., 2023). Required if 'team' is not specified. |
| `endWeek` | integer | No | Ending week filter to narrow stats to a specific window within the season (1-15+). |
| `startWeek` | integer | No | Starting week filter to narrow stats to a specific window within the season (1-15+). |
| `excludeGarbageTime` | boolean | No | When true, excludes garbage time plays (late blowout plays) for more meaningful efficiency stats. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Betting Lines

**Slug:** `COLLEGE_FOOTBALL_DATA_BETTING_LINES`

Tool to fetch betting lines and totals by game and provider. Use when you need current or historical betting line data filtered by specific criteria.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `away` | string | No | Filter by away team name (e.g., 'Clemson'). Only returns games where the specified team is away. |
| `home` | string | No | Filter by home team name (e.g., 'Alabama'). Only returns games where the specified team is home. |
| `team` | string | No | Filter by team name (e.g., 'Alabama', 'Ohio State'). Returns games where the team is either home or away. |
| `week` | integer | No | Week number within the season (1-15 for regular season, varies for postseason). |
| `year` | integer | No | Season year filter (e.g., 2023). |
| `gameId` | integer | No | Filter by specific game ID. |
| `conference` | string | No | Filter by conference abbreviation (e.g., 'SEC', 'Big Ten', 'ACC'). |
| `seasonType` | string ("regular" | "postseason") | No | Season type filter: 'regular' for regular season games, 'postseason' for bowl games and playoffs. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Composite Team Talent

**Slug:** `COLLEGE_FOOTBALL_DATA_COMPOSITE_TEAM_TALENT`

Fetches 247Sports composite team talent rankings for a given season. Returns a list of all FBS teams ranked by their composite talent score, which is based on aggregate recruit ratings. Higher scores indicate rosters with more highly-rated recruits.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `year` | integer | Yes | Season year for team talent data (e.g., 2024). Data is available from 2015 onwards. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Conference Memberships

**Slug:** `COLLEGE_FOOTBALL_DATA_CONFERENCE_MEMBERSHIPS_HISTORY`

Tool to retrieve current conference memberships for college football teams. Returns which teams belong to which conference, optionally filtered by conference. Use to find all teams in a specific conference or to see the current conference landscape.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `conference` | string | No | Filter by conference name or abbreviation. Common values: 'SEC', 'B1G' (Big Ten), 'ACC', 'B12' (Big 12), 'PAC' (Pac-12), 'MWC' (Mountain West), 'AAC' (American Athletic), 'SBC' (Sun Belt), 'CUSA' (Conference USA). Use LIST_CONFERENCES action to get valid values. If not provided, returns all teams across all conferences. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Divisions by Conference

**Slug:** `COLLEGE_FOOTBALL_DATA_DIVISIONS_BY_CONFERENCE`

Tool to list FBS/FCS conference divisions with active years and metadata. Use after specifying an optional season year to filter active divisions.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `year` | integer | No | Filter divisions active in the given season year (YYYY) |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Conference SP+ Ratings

**Slug:** `COLLEGE_FOOTBALL_DATA_GET_CONFERENCE_SP`

Retrieve aggregated historical conference SP+ (Success Rate + Points Per Play) ratings for college football conferences. Use this to get conference-level offensive, defensive, and special teams metrics aggregated from all teams in each conference. Filter by year to get specific season data, or by conference name to get historical ratings for a specific conference.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `year` | integer | No | Season year for which to retrieve conference SP+ ratings (YYYY format, e.g., 2023) |
| `conference` | string | No | Conference name or abbreviation to filter results (e.g., 'SEC', 'Big Ten', 'ACC') |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Drive Data

**Slug:** `COLLEGE_FOOTBALL_DATA_GET_DRIVE_DATA`

Retrieves college football drive-level data including offensive/defensive teams, yards gained, drive results (TD, PUNT, INT, etc.), time elapsed, and scoring information. Use to analyze drive efficiency, red zone performance, or game flow. Requires year; optionally filter by week, team, conference, or season type (regular/postseason).

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team` | string | No | Filter by team name (returns drives where team is on offense or defense). Use full school name like 'Alabama' or 'Ohio State'. |
| `week` | integer | No | Week number filter within the season (1-15 for regular season). |
| `year` | integer | Yes | Season year to filter drives (e.g., 2023). Required parameter. |
| `defense` | string | No | Filter by defensive team name. Returns only drives where this team is on defense. |
| `offense` | string | No | Filter by offensive team name. Returns only drives where this team is on offense. |
| `conference` | string | No | Filter by conference abbreviation (e.g., 'SEC', 'Big Ten', 'ACC'). Returns drives involving teams from this conference. |
| `seasonType` | string ("regular" | "postseason") | No | Season type filter: 'regular' for regular season or 'postseason' for bowl games and playoffs. |
| `defenseConference` | string | No | Filter by defensive team's conference abbreviation. |
| `offenseConference` | string | No | Filter by offensive team's conference abbreviation. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Field Goal Expected Points

**Slug:** `COLLEGE_FOOTBALL_DATA_GET_FIELD_GOAL_EXPECTED_POINTS`

Retrieves field goal expected points values for various field positions and distances. Returns static model data showing expected points for field goal attempts based on distance. Useful for analyzing field goal decision-making and expected value calculations.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### FPI Ratings

**Slug:** `COLLEGE_FOOTBALL_DATA_GET_FPI`

Retrieves historical Football Power Index (FPI) ratings for college football teams. FPI is ESPN's measure that predicts team strength and game outcomes. Use this to get team ratings, efficiency metrics, and resume rankings. Specify a year to get all teams' ratings for that season, or a team name to get historical ratings, or both for a specific team-season combination.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team` | string | No | Team name to filter FPI ratings (e.g. 'Alabama', 'Ohio State'). Required if year is not specified. Can be combined with year to get a specific team's rating for a specific season. |
| `year` | integer | No | Season year for which to retrieve FPI ratings (YYYY format, e.g. 2023). Required if team is not specified. |
| `conference` | string | No | Conference abbreviation to filter results (e.g., 'SEC', 'Big Ten', 'ACC'). Optional filter that can be combined with year. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Game Havoc Stats

**Slug:** `COLLEGE_FOOTBALL_DATA_GET_GAME_HAVOC_STATS`

Tool to retrieve havoc statistics aggregated by game. Use when you need game-level havoc metrics including DB havoc rate, front seven havoc rate, and total havoc events for offense and defense.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team` | string | No | Team filter by school name (e.g., 'Alabama', 'Ohio State'). Required if year is not specified. |
| `week` | integer | No | Optional week number filter within the season (e.g., 1-15 for regular season, 16+ for postseason). |
| `year` | integer | No | Season year filter (e.g., 2023). Required if team is not specified. |
| `opponent` | string | No | Optional opponent filter by school name (e.g., 'Clemson'). |
| `seasonType` | string ("regular" | "postseason" | "both" | "allstar" | "spring_regular" | "spring_postseason") | No | Season type enumeration for havoc stats queries. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Game Media

**Slug:** `COLLEGE_FOOTBALL_DATA_GET_GAME_MEDIA`

Retrieve broadcast information for college football games including TV channels, streaming platforms, and radio outlets. Use this to find where games are being broadcast. Returns information about the broadcaster/outlet, start time, and teams involved. Common use cases: - Find TV channel for a specific game: set year, week, and team - Get all broadcasts for a conference: set year and conference - Find streaming options: set mediaType='web' - Get bowl game broadcasts: set seasonType='postseason'

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team` | string | No | Team name to filter results (e.g., 'Alabama', 'Ohio State', 'Notre Dame') |
| `week` | integer | No | Week number within the season (1-15 for regular season, 1 for postseason/bowl games) |
| `year` | integer | Yes | Season year (required). Example: 2024 for the 2024-2025 season |
| `mediaType` | string ("tv" | "radio" | "web" | "ppv" | "mobile") | No | Filter by broadcast type: 'tv' for television, 'web' for streaming (ESPN+, Peacock), 'radio', 'ppv' for pay-per-view, 'mobile' |
| `conference` | string | No | Conference abbreviation to filter results (e.g., 'SEC', 'Big Ten', 'ACC', 'Big 12') |
| `seasonType` | string ("regular" | "postseason" | "both") | No | Filter by season type: 'regular' for regular season, 'postseason' for bowl games/playoffs, 'both' for all games |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Games and Results

**Slug:** `COLLEGE_FOOTBALL_DATA_GET_GAMES_AND_RESULTS`

Tool to retrieve college American football games and results for a given season/week/team. Use when you need game schedules or outcomes filtered by specific criteria. Covers NCAA only; NFL and other sports return no data. Overly narrow filter combinations (e.g., mismatched `team` and `conference`) may yield zero results — relax filters if the response is empty.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | integer | No | Single game filter by unique game ID. |
| `away` | string | No | Away team filter by school name. |
| `home` | string | No | Home team filter by school name. |
| `team` | string | No | Team filter by school name. |
| `week` | integer | No | Week filter within the season. |
| `year` | integer | Yes | Year/season filter for games. |
| `conference` | string | No | Conference abbreviation filter. |
| `seasonType` | string ("regular" | "postseason") | No | Season segment; e.g., regular or postseason. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Player Game Stats

**Slug:** `COLLEGE_FOOTBALL_DATA_GET_PLAYER_GAME_STATS`

Fetches detailed player statistics for college football games. Returns individual player stats (passing, rushing, receiving, defensive, kicking, etc.) organized by game and team. Use cases: - Get QB passing stats for a specific team's games - View rushing leaders for a conference in a given week - Analyze defensive stats for postseason games NOTE: Requires 'year' plus at least one of: 'week', 'team', or 'conference'. Use 'category' filter to limit results to specific stat types (recommended for faster responses).

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team` | string | No | Team name to filter by (e.g., 'Alabama', 'Ohio State'). Required if week and conference are not specified. |
| `week` | integer | No | Week number within the season (1-15 for regular season, higher for postseason). Required if team and conference are not specified. |
| `year` | integer | Yes | Required. Season year (e.g., 2023). Used with at least one of: week, team, or conference. |
| `gameId` | integer | No | Specific game ID to retrieve stats for. Can be obtained from get_games_and_results action. Must still provide week, team, or conference. |
| `category` | string ("passing" | "rushing" | "receiving" | "defensive" | "fumbles" | "interceptions" | "punting" | "puntReturns" | "kicking" | "kickReturns") | No | Filter stats by category. Options: 'passing' (QB stats), 'rushing' (RB/run stats), 'receiving' (WR/TE stats), 'defensive' (tackles, sacks), 'fumbles', 'interceptions', 'punting', 'puntReturns', 'kicking' (FG/XP), 'kickReturns'. |
| `conference` | string | No | Conference abbreviation to filter by (e.g., 'SEC', 'Big Ten', 'ACC', 'Big 12', 'Pac-12'). Required if week and team are not specified. |
| `seasonType` | string ("regular" | "postseason") | No | Filter by season phase: 'regular' for regular season games, 'postseason' for bowl games and playoffs. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Player Usage

**Slug:** `COLLEGE_FOOTBALL_DATA_GET_PLAYER_USAGE`

Retrieves player usage data for a given season. Returns usage percentages across different play situations (overall, passing, rushing, by down, etc.). Use this to analyze how frequently players are involved in plays, filtered by team, conference, position, or specific player.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team` | string | No | Team name filter (e.g., 'Alabama', 'Ohio State', 'Michigan'). Case-sensitive. |
| `year` | integer | Yes | Required. Season year for player usage data (e.g., 2023, 2024). |
| `playerId` | integer | No | Player ID filter to retrieve usage data for a specific player. |
| `position` | string | No | Position abbreviation filter (e.g., 'QB', 'RB', 'WR', 'TE', 'OL', 'DL', 'LB', 'DB'). |
| `conference` | string | No | Conference abbreviation filter (e.g., 'SEC', 'Big Ten', 'Big 12', 'ACC', 'Pac-12'). |
| `excludeGarbageTime` | boolean | No | Exclude garbage time plays from usage calculations. Defaults to false if not specified. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Play Types

**Slug:** `COLLEGE_FOOTBALL_DATA_GET_PLAY_TYPES`

Tool to fetch all available play types. Use when you need a catalog of play types for filtering or referencing play data.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Predicted Points Added By Team

**Slug:** `COLLEGE_FOOTBALL_DATA_GET_PREDICTED_POINTS_ADDED_BY_TEAM`

Tool to retrieve historical team Predicted Points Added (PPA) metrics by season. Use when you need season-level PPA performance data for teams to analyze offensive and defensive efficiency across play types and down situations.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team` | string | No | Team filter, required if year not specified. Team name or abbreviation to filter by. |
| `year` | integer | No | Year filter, required if team not specified. Season year to filter PPA data. |
| `conference` | string | No | Conference abbreviation filter to narrow results to a specific conference. |
| `excludeGarbageTime` | boolean | No | If true, exclude garbage time plays from PPA calculations. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Pregame Win Probabilities

**Slug:** `COLLEGE_FOOTBALL_DATA_GET_PREGAME_WIN_PROBABILITIES`

Tool to retrieve pregame win probabilities for college football games. Use when you need predictive data about game outcomes before they are played, filtered by season, week, or team.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team` | string | No | Filter by team name (e.g., 'Alabama', 'Ohio State'). Returns games where the specified team is either home or away. |
| `week` | integer | No | Week number filter within the season (1-15 for regular season, varies for postseason). Narrows results to a specific week. |
| `year` | integer | No | Season year filter (e.g., 2024). Returns win probabilities for games in the specified season. |
| `seasonType` | string ("regular" | "postseason" | "both" | "allstar" | "spring_regular" | "spring_postseason") | No | Season type for filtering pregame win probabilities. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Recruits

**Slug:** `COLLEGE_FOOTBALL_DATA_GET_RECRUITS`

Retrieves player recruiting rankings from the College Football Data API. Returns detailed information about high school, prep school, and junior college recruits including star ratings, composite ratings, rankings, physical measurements, and commitment status. Use this action to analyze recruiting classes by year or team, compare recruits by position or location, or track where top prospects commit. At least one of year or team parameters must be provided.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team` | string | No | Team filter by school name (e.g., 'Alabama', 'Ohio State'). Required when year is not specified. |
| `year` | integer | No | Year filter for recruiting class (e.g., 2023, 2024). Required when team is not specified. |
| `state` | string | No | Optional state/province filter to narrow results by recruit's home state (e.g., 'FL', 'TX', 'CA'). |
| `position` | string | No | Optional position categorization filter (e.g., 'QB', 'WR', 'RB', 'OL', 'DL'). Use to filter recruits by position. |
| `classification` | string ("JUCO" | "PrepSchool" | "HighSchool") | No | Classification types for recruits. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Stats Categories

**Slug:** `COLLEGE_FOOTBALL_DATA_GET_STATS_CATEGORIES`

Tool to fetch all available team statistical categories. Use when you need to discover valid category names for statistical analysis or filtering team stats.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Team Game Stats

**Slug:** `COLLEGE_FOOTBALL_DATA_GET_TEAM_GAME_STATS`

Fetch team-level box score statistics for college football games. Returns detailed game stats including offense (rushing/passing yards, TDs, turnovers), defense (tackles, sacks, interceptions), and special teams (kick/punt returns) for each team. Use cases: - Get box scores for a specific team's games in a season - Compare team performance across conference games in a given week - Analyze offensive/defensive stats for a specific matchup Note: At least one of week, team, or conference must be provided to filter results.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team` | string | No | Team school name to filter by (e.g., 'Alabama', 'Ohio State', 'Michigan'). Required unless week or conference is provided. |
| `week` | integer | No | Week number (1-20). Required unless team or conference is provided. Weeks 1-15 are regular season, 16+ are postseason. |
| `year` | integer | Yes | Required. Season year (e.g., 2024). College football data is available from 1869 onwards. |
| `gameId` | integer | No | Specific game ID filter. Can be combined with week/team/conference for targeted lookup. Does not satisfy the requirement for week/team/conference alone. |
| `conference` | string | No | Conference abbreviation filter. Common values: 'SEC', 'B1G' (Big Ten), 'Big 12', 'ACC', 'Pac-12'. Required unless week or team is provided. |
| `seasonType` | string ("regular" | "postseason") | No | Season type filter. Use 'regular' for regular season games or 'postseason' for bowl games and playoffs. Defaults to all types if not specified. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Team Recruiting Rankings

**Slug:** `COLLEGE_FOOTBALL_DATA_GET_TEAM_RECRUITING_RANKINGS`

Retrieve team recruiting rankings from the College Football Data API. Returns composite recruiting rankings based on recruit star ratings and commitments. Use to compare recruiting success across teams or track a team's recruiting performance over time.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team` | string | No | Optional filter by team name. Use exact team name (e.g., 'Alabama', 'Ohio State'). Returns rankings only for the specified team. |
| `year` | integer | No | Optional filter for recruiting class year (YYYY format). Returns rankings for the specified recruiting year. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Teams ATS Records

**Slug:** `COLLEGE_FOOTBALL_DATA_GET_TEAMS_ATS`

Tool to retrieve against-the-spread (ATS) summary by team. Use when you need historical betting performance data showing how teams performed relative to point spreads.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team` | string | No | Optional team filter (e.g., 'Alabama', 'Ohio State'). |
| `year` | integer | Yes | Required year filter for which to retrieve ATS statistics. |
| `conference` | string | No | Optional conference filter (e.g., 'SEC', 'Big Ten', 'ACC'). |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get User Info

**Slug:** `COLLEGE_FOOTBALL_DATA_GET_USER_INFO`

Retrieves information about the authenticated user from the College Football Data API. Returns the user's Patreon subscription level and remaining API calls for rate limit monitoring. Use this to check your current API quota and subscription status.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Win Probability

**Slug:** `COLLEGE_FOOTBALL_DATA_GET_WIN_PROBABILITY`

Tool to query play-by-play win probabilities for a specific game. Use when you need detailed probability metrics showing how win likelihood changed throughout the game.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `gameId` | integer | Yes | Required game ID to retrieve win probability data for. Must be a valid game identifier. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Coaches and History

**Slug:** `COLLEGE_FOOTBALL_DATA_LIST_COACHES_AND_HISTORY`

Tool to get coaching records and history. Use when you need coaches’ season-by-season data with optional filters.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team` | string | No | Filter by team or school name |
| `year` | integer | No | Filter by specific season year |
| `maxYear` | integer | No | Filter by maximum season year (inclusive) |
| `minYear` | integer | No | Filter by minimum season year (inclusive) |
| `lastName` | string | No | Filter by coach's last name |
| `firstName` | string | No | Filter by coach's first name |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Conferences

**Slug:** `COLLEGE_FOOTBALL_DATA_LIST_CONFERENCES`

Retrieves all college football conferences from the College Football Data API. Returns conferences across all NCAA divisions (FBS, FCS, Division II, Division III). Use this to get conference IDs for filtering other API calls or to display conference information. No parameters required - returns the complete list of conferences.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List FBS Teams

**Slug:** `COLLEGE_FOOTBALL_DATA_LIST_FBS_TEAMS`

Tool to list FBS teams for a given season. Use after selecting the season year to retrieve all FBS teams.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `year` | integer | No | Season year to filter FBS teams (e.g., 2025) |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List FCS Teams

**Slug:** `COLLEGE_FOOTBALL_DATA_LIST_FCS_TEAMS`

Tool to list FCS teams for a given season and conference. Use when you need a list of FCS programs filtered by season year and conference.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `year` | integer | No | Season year to filter FCS teams (e.g., 2025) |
| `conference` | string | No | Conference to filter FCS teams (e.g., 'SoCon') |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Teams

**Slug:** `COLLEGE_FOOTBALL_DATA_LIST_TEAMS`

Retrieve a list of college football teams from the CFBD (College Football Data) API. Use this action to: - Get all college football teams (call with no parameters) - Get teams from a specific season (use year parameter) - Get teams from a specific conference (use conference parameter) - Combine filters to get conference teams for a specific season Returns team details including: name, mascot, abbreviation, conference, classification (FBS/FCS/D2/D3), team colors, logos, Twitter handle, and stadium/venue information.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `year` | integer | No | Filter teams by season year (YYYY format). Returns teams that existed in the specified season. Without this filter, returns all teams including historical ones. |
| `conference` | string | No | Filter by conference abbreviation. Common values: 'SEC', 'B1G' (Big Ten), 'ACC', 'Big 12', 'Pac-12', 'AAC', 'MWC', 'Sun Belt', 'MAC', 'CUSA'. Use LIST_CONFERENCES action to get all valid conference abbreviations. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Venues and Stadiums

**Slug:** `COLLEGE_FOOTBALL_DATA_LIST_VENUES_STADIUMS`

Tool to list college football venues with metadata (name, capacity, location, etc.). Use when you need detailed venue information for a specific season.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `year` | integer | No | Season year in YYYY format to filter venues |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### NFL Draft Picks

**Slug:** `COLLEGE_FOOTBALL_DATA_NFL_DRAFT_PICKS`

Tool to list NFL Draft picks. Use when you need draft pick data by year, round, team, player, etc.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `pick` | integer | No | Pick number within the round |
| `team` | string | No | NFL team location name (e.g., 'Carolina', 'New England', 'Houston'). Use COLLEGE_FOOTBALL_DATA_NFL_DRAFT_TEAMS to get valid team names. |
| `year` | integer | Yes | Draft year (e.g., 2025) |
| `limit` | integer | No | Maximum number of results to return |
| `round` | integer | No | Draft round number (starting at 1) |
| `offset` | integer | No | Number of results to skip for paging |
| `school` | string | No | College program name filter (e.g., 'Alabama', 'Ohio State') |
| `overall` | integer | No | Overall pick number |
| `position` | string | No | Player position filter. Use COLLEGE_FOOTBALL_DATA_NFL_DRAFT_POSITIONS to get valid position values. |
| `conference` | string | No | College conference name filter (e.g., 'SEC', 'Big Ten') |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### NFL Draft Positions

**Slug:** `COLLEGE_FOOTBALL_DATA_NFL_DRAFT_POSITIONS`

Retrieves the standardized list of NFL draft positions. Returns all position names and abbreviations used to classify players in NFL drafts. Useful for filtering draft picks by position or understanding position categories in draft analysis. No parameters required.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### NFL Draft Teams

**Slug:** `COLLEGE_FOOTBALL_DATA_NFL_DRAFT_TEAMS`

Tool to list NFL teams used in draft endpoints. Use when preparing to retrieve NFL draft data by team.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Play-by-Play Data

**Slug:** `COLLEGE_FOOTBALL_DATA_PLAY_BY_PLAY_DATA`

Tool to fetch play-by-play data for college football games. Use when you need detailed play logs filtered by season, week, team, or game.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team` | string | No | Team name filter (school name or abbreviation) |
| `week` | integer | Yes | Week number within the season |
| `year` | integer | Yes | 4-digit season year filter |
| `gameId` | integer | No | Specific game ID filter |
| `defense` | string | No | Defense team filter (school name or abbreviation) |
| `offense` | string | No | Offense team filter (school name or abbreviation) |
| `playType` | string | No | Play type filter (e.g., pass, run) |
| `conference` | string | No | Conference abbreviation filter (e.g., SEC) |
| `seasonType` | string ("regular" | "postseason") | No | Season phase filter; 'regular' or 'postseason' |
| `defenseConference` | string | No | Defense conference abbreviation filter (e.g., ACC) |
| `offenseConference` | string | No | Offense conference abbreviation filter (e.g., SEC) |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Play Stats Player

**Slug:** `COLLEGE_FOOTBALL_DATA_PLAY_STATS_PLAYER`

Fetch player-level statistics tied to individual plays. Returns detailed stats for each player's contribution to a play (rushes, receptions, completions, etc.). Use this when you need: - Play-by-play player statistics - Granular data on individual player performance per play - Analysis of a specific athlete's game contributions Note: Recommend filtering by year/week/team or gameId to limit result size.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team` | string | No | Team name filter (school name, e.g., 'Alabama', 'Ohio State'). |
| `week` | integer | No | Week number filter within the season (1-25). |
| `year` | integer | No | Season year filter (e.g., 2024). Recommended to always specify. |
| `gameId` | integer | No | Filter by specific CFBD game ID. |
| `athleteId` | integer | No | Filter by specific CFBD athlete ID. |
| `seasonType` | string ("regular" | "postseason" | "both") | No | Season type filter: 'regular', 'postseason', or 'both'. |
| `statTypeId` | integer | No | Filter by specific stat type ID (see Play Stat Types endpoint for valid IDs). |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Play Stat Types

**Slug:** `COLLEGE_FOOTBALL_DATA_PLAY_STAT_TYPES`

Tool to fetch all play-level stat type definitions. Use when you need a catalog of available play stat types for filtering or referencing.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Player PPA by Game

**Slug:** `COLLEGE_FOOTBALL_DATA_PPA_PLAYER_BY_GAME_ACTION`

Retrieve player-level PPA (Predicted Points Added) / EPA (Expected Points Added) stats for individual games. PPA measures how many points a player adds/subtracts compared to average performance on similar plays. Use this tool to analyze individual player contributions per game, filtered by season, week, team, or position. IMPORTANT: Either 'week' OR 'team' must be specified in the request.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team` | string | No | Team school name (e.g., 'Alabama', 'Ohio State'). Required if 'week' is not specified. Case-sensitive. |
| `week` | integer | No | Week number to filter (1-15 regular season, higher for postseason). Required if 'team' is not specified. |
| `year` | integer | No | Season year to filter PPA stats (e.g., 2023). Highly recommended for efficient queries. |
| `playerId` | integer | No | Unique player ID to filter for a specific player. Still requires 'week' or 'team' to be set. |
| `position` | string | No | Position filter: QB (Quarterback), RB (Running Back), WR (Wide Receiver), TE (Tight End). |
| `threshold` | string | No | Minimum number of plays threshold. Only returns players with at least this many plays in the game. |
| `excludeGarbageTime` | boolean | No | If true, exclude garbage time plays (low-leverage plays in blowout games) from calculations. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### PPA Player By Season

**Slug:** `COLLEGE_FOOTBALL_DATA_PPA_PLAYER_BY_SEASON`

Tool to fetch player-level PPA/EPA aggregated by season. Use when you need seasonal PPA metrics for specific players or groups after applying filters.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team` | string | No | Team name to filter by (e.g., 'Alabama', 'Ohio State'). |
| `year` | integer | No | Season year to filter results (e.g., 2023). |
| `playerId` | integer | No | CFBD player ID to retrieve PPA data for a specific player across all seasons. |
| `position` | string | No | Position abbreviation to filter by (e.g., 'QB'). |
| `threshold` | string | No | Minimum number of plays a player must have to be included in results. |
| `conference` | string | No | Conference abbreviation to filter by (e.g., 'SEC'). |
| `excludeGarbageTime` | boolean | No | If true, exclude garbage time plays from calculations. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Predict Expected Points (EP)

**Slug:** `COLLEGE_FOOTBALL_DATA_PPA_PREDICTED_POINTS_EP`

Get expected points (EP) for all field positions given a specific down and distance scenario. Returns expected points values for yard lines 1-99, useful for analyzing game situations and fourth-down decisions. Common scenarios: 1st and 10, 3rd and short, 4th and goal.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `down` | integer | Yes | The down number (1-4). Example: 1 for 1st down, 3 for 3rd down. |
| `distance` | integer | Yes | Distance to go in yards (yards needed for a first down). Example: 10 for 1st and 10. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### PPA Team By Game

**Slug:** `COLLEGE_FOOTBALL_DATA_PPA_TEAM_BY_GAME`

Tool to retrieve team Predicted Points Added (PPA) by game. Use when you need team-level PPA metrics for games after filtering by season, week, team, or date.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team` | string | No | Team filter by school name or abbreviation. |
| `week` | integer | No | Week number filter within the season. |
| `year` | integer | Yes | Season year to filter PPA by game. |
| `endDate` | string | No | Filter games on or before this date (YYYY-MM-DD). |
| `startDate` | string | No | Filter games on or after this date (YYYY-MM-DD). |
| `conference` | string | No | Conference abbreviation filter. |
| `seasonType` | string ("regular" | "postseason") | No | Season segment: 'regular' or 'postseason'. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Rankings Polls

**Slug:** `COLLEGE_FOOTBALL_DATA_RANKINGS_POLLS`

Retrieve college football poll rankings (AP Top 25, Coaches Poll, Playoff Committee, FCS, Division II/III). Returns weekly rankings including team rank, school name, conference, first-place votes, and points. Use this tool to look up historical or current poll standings for any season from 1900 to present. Required: year (e.g., 2023). Optional: season_type (regular/postseason), week number.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `week` | integer | No | Optional week number of the season to retrieve rankings |
| `year` | integer | Yes | Season year in YYYY format to filter rankings |
| `season_type` | string ("regular" | "postseason" | "both" | "allstar" | "spring_regular" | "spring_postseason") | No | Optional season type filter. One of: 'regular', 'postseason', 'both', 'allstar', 'spring_regular', 'spring_postseason' |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Elo Ratings

**Slug:** `COLLEGE_FOOTBALL_DATA_RATINGS_ELO`

Tool to retrieve Elo ratings for college football teams. Use when you need historical Elo ratings by season or for a specific team.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team` | string | No | Team name to filter Elo ratings for a single team |
| `year` | integer | No | Season year for which to retrieve Elo ratings (YYYY) |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### SP+ Ratings

**Slug:** `COLLEGE_FOOTBALL_DATA_RATINGS_SP_PLUS`

Retrieve SP+ (Success Rate + Points Per Play) team ratings for college football. SP+ is an advanced tempo- and opponent-adjusted measure of college football efficiency. Use this to get overall team ratings, offensive/defensive rankings, and special teams metrics. Specify a year to get all teams' ratings for that season, or a team name to get historical ratings across seasons, or both for a specific team-season combination.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team` | string | No | Team name to filter SP+ ratings (e.g. 'Alabama', 'Ohio State'). Required if year is not specified. Can be combined with year to get a specific team's rating for a specific season. |
| `year` | integer | No | Season year for which to retrieve SP+ ratings (YYYY format, e.g. 2023). Required if team is not specified. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### SRS Ratings

**Slug:** `COLLEGE_FOOTBALL_DATA_RATINGS_SRS`

Retrieves Simple Rating System (SRS) team ratings. SRS measures team strength based on point differential adjusted for strength of schedule. Either year or team parameter must be provided. Use year to get all teams' ratings for a season, or team to get historical ratings for a specific team.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team` | string | No | Full team name (e.g., 'Alabama', 'Ohio State'). Required if year is not specified. Returns historical ratings for the team. |
| `year` | integer | No | Season year (YYYY format). Required if team is not specified. Returns all team ratings for the given season. |
| `conference` | string | No | Conference abbreviation to filter results (e.g., 'SEC', 'Big Ten', 'ACC', 'Big 12', 'Pac-12'). Optional filter. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Recruiting Group Dictionary

**Slug:** `COLLEGE_FOOTBALL_DATA_RECRUITING_GROUP_DICTIONARY`

Retrieves aggregated college football recruiting data grouped by position. Use this tool to analyze recruiting performance by position group for specific teams or conferences. Returns composite ratings, star averages, and commit counts by position group (e.g., Quarterback, Receiver, Defensive Back). Useful for comparing recruiting strength across different positions or evaluating team/conference recruiting patterns.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team` | string | No | Full team name to filter results (e.g., 'Alabama'). |
| `endYear` | integer | No | Inclusive end year for recruiting data aggregation; must be >= startYear. |
| `startYear` | integer | No | Inclusive start year for recruiting data aggregation. |
| `conference` | string | No | Conference abbreviation to filter results (e.g., 'SEC'). |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Recruiting Transfer Portal

**Slug:** `COLLEGE_FOOTBALL_DATA_RECRUITING_TRANSFER_PORTAL`

Retrieves NCAA college football transfer portal entries for a given season. Returns player transfer information including origin school, destination school (if committed), position, star rating, transfer rating, transfer date, and eligibility status. Useful for tracking player movement between schools, analyzing transfer trends, and identifying key transfers. Data is available from 2021 onwards when the transfer portal became widely used.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `year` | integer | Yes | Season year for transfer portal data (e.g., 2024, 2025). Data available from 2021 onwards. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Returning Production by Team

**Slug:** `COLLEGE_FOOTBALL_DATA_RETURNING_PRODUCTION_TEAM`

Tool to fetch Bill Connelly–style returning production splits by team and season. Use when evaluating returning offense, defense, and overall production for teams in a given season.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team` | string | No | Team name to filter results (e.g., 'Alabama', 'Ohio State'). Required if year is not specified. |
| `year` | integer | No | Season year (YYYY) to query returning production data. Required if team is not specified. |
| `conference` | string | No | Conference abbreviation to filter results (e.g., 'SEC', 'Big Ten'). Only used alongside year or team. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Search Players

**Slug:** `COLLEGE_FOOTBALL_DATA_SEARCH_PLAYERS`

Search for college football players by name. Returns top 100 results matching the search term. Use this action to find players by name and optionally filter by year, team, or position.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team` | string | No | Optional team name filter to narrow search to players from a specific team (e.g., 'Alabama', 'Ohio State'). |
| `year` | integer | No | Optional year filter to narrow search to players active in a specific season. |
| `position` | string | No | Optional position abbreviation filter to narrow search to players at a specific position (e.g., 'QB', 'RB', 'WR', 'LB', 'DB'). |
| `searchTerm` | string | Yes | Search term for matching player name (first name, last name, or full name). Returns top 100 results matching the search term. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Season Stats Player

**Slug:** `COLLEGE_FOOTBALL_DATA_SEASON_STATS_PLAYER`

Fetch aggregated season statistics for college football players. Returns individual player stats by category (passing, rushing, receiving, defensive, kicking, etc.) for a specified year. Useful for comparing player performance across a season or filtering by team/conference.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team` | string | No | Filter by team school name (e.g., 'Alabama', 'Ohio State', 'Michigan'). Case-sensitive. |
| `year` | integer | Yes | Required. Season year for player stats (e.g., 2023, 2024). |
| `endWeek` | integer | No | Filter stats up to this week number (inclusive). Use with startWeek to define a range. |
| `category` | string | No | Filter by stat category. Common values: 'passing', 'rushing', 'receiving', 'defensive', 'interceptions', 'kicking', 'punting', 'kickReturns', 'puntReturns'. |
| `startWeek` | integer | No | Filter stats from this week number onward (inclusive). Week 1 is the season start. |
| `conference` | string | No | Filter by conference abbreviation (e.g., 'SEC', 'Big Ten', 'Big 12', 'ACC', 'Pac-12'). |
| `seasonType` | string ("regular" | "postseason" | "both") | No | Season phase filter. Options: 'regular' (default), 'postseason', or 'both'. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Season Team Stats

**Slug:** `COLLEGE_FOOTBALL_DATA_SEASON_STATS_TEAM`

Tool to get basic season stats aggregated by team and season. Use when you need a summary of team-level statistics for a particular season.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team` | string | No | Filter by school/team name, e.g., 'Alabama' |
| `year` | integer | Yes | Season year in YYYY format (e.g., 2023 for the 2023 college football season) |
| `endWeek` | integer | No | Ending week number (must be >= startWeek) |
| `startWeek` | integer | No | Starting week number (1-based) |
| `conference` | string | No | Filter by conference abbreviation (e.g., 'SEC', 'B1G', 'ACC', 'Big 12', 'Pac-12') |
| `seasonType` | string ("regular" | "postseason" | "both") | No | Season type to include: 'regular', 'postseason', or 'both' |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Season Types Dictionary

**Slug:** `COLLEGE_FOOTBALL_DATA_SEASON_TYPES_DICTIONARY`

Retrieve the list of available season types for a specific college football year. Returns types like 'regular', 'postseason', and for certain years 'spring_regular', 'spring_postseason'. Use this to discover valid seasonType values to pass to other endpoints.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `year` | integer | Yes | The season year to retrieve available season types for. Required. Common types include 'regular' and 'postseason'. Some years (like 2020-2021) may have additional types such as 'spring_regular' and 'spring_postseason'. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Team Matchup History

**Slug:** `COLLEGE_FOOTBALL_DATA_TEAM_MATCHUP_HISTORY`

Tool to retrieve head-to-head team matchup records over a date range. Use after selecting two FBS teams to compare their matchup history.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team1` | string | Yes | First team name (FBS) to query head-to-head history. |
| `team2` | string | Yes | Second team name (FBS) to query head-to-head history. |
| `maxYear` | integer | No | Maximum season year (YYYY) to include in results. |
| `minYear` | integer | No | Minimum season year (YYYY) to include in results. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get team season records

**Slug:** `COLLEGE_FOOTBALL_DATA_TEAM_RECORDS`

Retrieve college football team win-loss records for a specific season. Returns detailed breakdowns including total, conference, home, away, neutral site, regular season, and postseason records. Requires a year parameter. Optionally filter by team name, conference, division, or season type.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team` | string | No | Team/school name filter (e.g., 'Alabama', 'Ohio State', 'Michigan'). |
| `year` | integer | Yes | Season year for which to retrieve team records (must be >= 1869). |
| `limit` | integer | No | Limit the number of results returned (for pagination). |
| `offset` | integer | No | Number of records to skip for pagination. |
| `division` | string ("fbs" | "fcs" | "d1" | "d2" | "d3") | No | NCAA division filter: 'fbs' (Division I FBS), 'fcs' (Division I FCS), 'd1', 'd2', or 'd3'. |
| `conference` | string | No | Conference abbreviation filter (e.g., 'SEC', 'ACC', 'Big Ten', 'Big 12', 'Pac-12'). |
| `seasonType` | string ("regular" | "postseason" | "all") | No | Type of season to include: 'regular', 'postseason', or 'all'. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Team Roster

**Slug:** `COLLEGE_FOOTBALL_DATA_TEAM_ROSTER`

Fetches the roster for a college football team for a specific season. Returns player details including name, position, height, weight, jersey number, academic year, and hometown info. Use this to get player information for any FBS or FCS team from 2009 onwards.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team` | string | Yes | Team name (e.g., 'Alabama', 'Ohio State', 'Michigan'). Must be exact team name. |
| `year` | integer | Yes | Season year for the roster (2009-present). |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |