AD Vantage

Returns the FULL FRS (Financial Reporting System) report for a university and reporting year. Includes one row per department/sport plus the university-wide rollup (departmentId = -1). Each row contains totalExpenses, totalRevenue, headCoachSalary, totalProgramSalaries, coachEffect, totalAthletes, recruitingBudget, ticketSales, and the headCoachId. Use this when the user asks for a per-sport breakdown of athletic-department finances. For just the university-wide totals (one row), use frs_summary instead. Response includes a top-level `sources` array of {kind,label,url} links into the ADvantage web app. Cite them as reference footnotes beneath your answer. For the dedicated demo account, only five sample workflows are available. Results are synthetic; sources reference MCP demo resources rather than production web pages.

Per-department (per-sport) FRS benchmarks across conference peers. Returns the DepartmentMetricSummary for one departmentId at every school in the conference, for one reporting year. Sorted by totalRevenue desc. Conference defaults to the caller's. Pass conferenceId to view another. Use when the user asks: - "How does Alabama football's spending compare to the rest of the SEC?" - "Per-sport conference benchmarks." - "Show me revenue for football across the Big 12." For the WHOLE-univ rollup across conference peers, use frs_conferenceSummary. For an explicit list of schools (any conference), use frs_compareUniversities. To discover departmentId values, call frs_reportForUniversity first and look at the returned departmentId fields. Response includes a top-level `sources` array of {kind,label,url} links into the ADvantage web app. Cite them as reference footnotes beneath your answer. For the dedicated demo account, only five sample workflows are available. Results are synthetic; sources reference MCP demo resources rather than production web pages.

Returns the FRS (Financial Reporting System) high-level totals for a university and reporting year. By default the summary is scoped to the caller's university. Pass universityId to override. Output fields include: - totalExpenses, totalRevenue, netIncome - totalProgramSalaries, headCoachSalary - costPerAthlete, costPerCoachEffectPoint - recruitingBudget, ticketSales - totalAthletes, coachEffect Use when the user asks about a school's overall athletic-department finances (for individual sport / department detail, use frs_departmentDetail). Response includes a top-level `sources` array pointing at the FRS dashboard scoped to the same university + year. It is attached centrally — see src/tool-sources.ts. Response includes a top-level `sources` array of {kind,label,url} links into the ADvantage web app. Cite them as reference footnotes beneath your answer. For the dedicated demo account, only five sample workflows are available. Results are synthetic; sources reference MCP demo resources rather than production web pages.

Return warehouse-wide game-guarantee data coverage: - gameCount: total number of distinct games-in-series across all contracts - contractCount: total number of distinct contracts on file Use when the user asks: - "How many guarantee contracts do we have?" - "How complete is our game-guarantee data?" - "Quick coverage snapshot." This is global — not scoped to the caller's university. For per-university guarantee data, use guarantees_search with a universityId filter. Response includes a top-level `sources` array of {kind,label,url} links into the ADvantage web app. Cite them as reference footnotes beneath your answer. For the dedicated demo account, only five sample workflows are available. Results are synthetic; sources reference MCP demo resources rather than production web pages.

Fetch a single game-guarantee contract by its documentId. Returns the full contract record including resolved parties (which universities/organizations are bound to the agreement, and which staff members signed) plus breach terms and full series detail. Pass the documentId from a prior guarantees_search result. Returns null if no current game-guarantee structured output exists for that document. Response includes a top-level `sources` array of {kind,label,url} links into the ADvantage web app. Cite them as reference footnotes beneath your answer. For the dedicated demo account, only five sample workflows are available. Results are synthetic; sources reference MCP demo resources rather than production web pages.

Search ADVantage game-guarantee contracts. Returns slim flat-rows — one per game-in-series — matching the supplied filters. For full contract detail (parties, breach terms, document URL, full series), follow up with guarantees_get(documentId). Use when the user asks about: - Specific guarantee dollar amounts ("what are the largest guarantees in football") - A school's guarantee history ("show Alabama's guarantees") - Conference-wide guarantee patterns - Year-over-year guarantee trends If no universityId is supplied the search defaults to the caller's own university. Pass universityId explicitly to query a different school. Date filters (dateFrom/dateTo) match on the per-game gameDate, NOT the contract date. A series contract with games outside the range will only return the games inside it. Response includes a top-level `sources` array of {kind,label,url} links into the ADvantage web app. Cite them as reference footnotes beneath your answer. For the dedicated demo account, only five sample workflows are available. Results are synthetic; sources reference MCP demo resources rather than production web pages.

Return the curated AD-industry news feed (same items the web app's home dashboard shows under "Latest Industry News"). Each item carries title, description, publication date (pretty-formatted: "today" / "yesterday" / "N days ago"), source domain, and an optional image URL. Cached in-process for 15 minutes — back-to-back calls are cheap. Use when the user asks: - "What's the latest industry news?" - "Show me the news feed from the home page." - "Any recent headlines on college athletics?" Response includes a top-level `sources` array of {kind,label,url} links into the ADvantage web app. Cite them as reference footnotes beneath your answer. For the dedicated demo account, only five sample workflows are available. Results are synthetic; sources reference MCP demo resources rather than production web pages.

Return the full "My Programs" grid for one university — one card per coaching sport, each with the head coach (name, photo, coach effect, coach-since date), a summary performance stat with YoY trend + conference rank, and total operating revenues + expenses with YoY trends + conference ranks. This is THE dashboard call for the home page: it composes six repos server-side and returns everything a program-card UI needs in a single response. Prefer this over manually joining staff_search + frs_reportForUniversity when you want the same view the web app shows. Defaults to the caller's school. Pass universityId to view another program. Use when the user asks: - "Show me my home dashboard." - "Give me an overview of every sport at Alabama." - "What's the program-card grid for Florida?" Response includes a top-level `sources` array of {kind,label,url} links into the ADvantage web app. Cite them as reference footnotes beneath your answer. For the dedicated demo account, only five sample workflows are available. Results are synthetic; sources reference MCP demo resources rather than production web pages.

Also known as "Staff Performance Impact Analysis" in the web app. Analyze staff performance on a specific stat, comparing their BASELINE years-ago rankings vs. their MOST RECENT N years (rather than first N). Backs /insights/recent-performance-analysis. Requires an active, provisioned AD Vantage Customer User with Core and MCP access; sign-in alone does not grant access. REQUIRES sportId, titleIds, and statKey. Discover valid stat keys per sport via insights_statKeys. Returns rows with staff id/name, university, conference, tenure window, ranks baseline vs. recent, avg ranks, absolute + percent improvement, overall rank, program budget, AND a financial-efficiency score (roughly $/rank-point) so you can see who's getting the most improvement per dollar spent. This uses a moving "last N years" window instead of a fixed "first N years from hire". Use this for "how are they doing lately?" Use when the user asks: - "Which head football coaches have improved the most in the last 3 years?" - "Show me softball head coaches with the best recent RPI trend." - "Which programs are getting the most improvement per dollar spent?" Response includes a top-level `sources` array of {kind,label,url} links into the ADvantage web app. Cite them as reference footnotes beneath your answer. For the dedicated demo account, only five sample workflows are available. Results are synthetic; sources reference MCP demo resources rather than production web pages.

Helper. List the stat keys measurable for a given sport (id from catalog_list). Optionally scope to a specific reporting year. Requires an active, provisioned AD Vantage Customer User with Core and MCP access; sign-in alone does not grant access. Use this BEFORE calling insights_recentPerformanceAnalysis to discover which stat keys are valid — the performance tool requires a specific statKey. Returns an array of { key, displayName, sport, description? } entries. Use when the user asks: - "What stats can I rank football coaches on?" - "What are the available metrics for baseball performance analysis?" Response includes a top-level `sources` array of {kind,label,url} links into the ADvantage web app. Cite them as reference footnotes beneath your answer. For the dedicated demo account, only five sample workflows are available. Results are synthetic; sources reference MCP demo resources rather than production web pages.

Batch version of staff_careerHistory. Fetch appointment timelines for up to 25 staff members in one MCP call. Each timeline includes institution, title, sport, and start/end dates, so this is the preferred way to verify tenure for a set of coaches or athletic directors. Use this whenever research requires career or tenure evidence for two or more people. Do not loop over staff_careerHistory or infer institutional tenure from compensation records when this tool can provide the appointment dates directly. Response includes a top-level `sources` array of {kind,label,url} links into the ADvantage web app. Cite them as reference footnotes beneath your answer. For the dedicated demo account, only five sample workflows are available. Results are synthetic; sources reference MCP demo resources rather than production web pages.

Return the career history for one coach — every appointment row with start/end dates, university, title(s), sport(s), and role description. Use when the user asks: - "Where has this coach worked?" - "Show me his career timeline." - "What sports has she coached over her career?" For the full profile (bio + accomplishments + comp + career), use staff_profile. This is the career timeline only. For two or more staff members, use staff_careerHistories instead of calling this tool repeatedly. Response includes a top-level `sources` array of {kind,label,url} links into the ADvantage web app. Cite them as reference footnotes beneath your answer. For the dedicated demo account, only five sample workflows are available. Results are synthetic; sources reference MCP demo resources rather than production web pages.

Batch version of staff_coachEffectHistory. Fetch coach-effect histories for up to 25 staff members in one MCP call. Results preserve input order, deduplicate IDs, and isolate per-person errors. Use this whenever research requires coach-effect history for two or more people. Do not loop over staff_coachEffectHistory sequentially. Keep includePerformanceStats=false unless the underlying rank arrays are needed, because those blobs can make a multi-person response very large. Response includes a top-level `sources` array of {kind,label,url} links into the ADvantage web app. Cite them as reference footnotes beneath your answer. For the dedicated demo account, only five sample workflows are available. Results are synthetic; sources reference MCP demo resources rather than production web pages.

Return the historical coach-effect (performance score) time series for one coach. Includes every season on file, the team and sport each season, and the baseline window the model used. Use when the user asks: - "How has Kalen DeBoer's coach effect changed over time?" - "Show me his year-over-year performance trajectory." - "Did his coach effect jump when he moved from Fresno State to Washington?" Response is grouped three ways: - allRecords: flat array of every season - bySport: records grouped by sport name - latestPerSport: the most recent record per sport (the "current" CE) By default the heavy performanceStats blob is dropped per record (per-university rank-before / rank-during arrays + weighted averages). Pass includePerformanceStats=true to keep them — useful for understanding WHY the model assigned a given CE. For two or more staff members, use staff_coachEffectHistories instead of calling this tool repeatedly. Response includes a top-level `sources` array of {kind,label,url} links into the ADvantage web app. Cite them as reference footnotes beneath your answer. For the dedicated demo account, only five sample workflows are available. Results are synthetic; sources reference MCP demo resources rather than production web pages.

Return the directed coaching-lineage graph anchored on one coach: mentors (people they coached UNDER) and mentees (people they coached/hired who later moved on). Each node carries the overlap window (in months) and the node's coach effect score. Use when the user asks: - "Who has Kalen DeBoer coached?" - "What's Bill Belichick's coaching tree?" - "List the head coaches who came out of Saban's Alabama staffs." By default mentees are filtered to people whose primary category is coaching (category_id = 20). Pass includeNonCoachingMentees=true to see staff (analysts, admins, support) who later moved on. Default minimum overlap with a mentee = 24 months. Override with minOverlapMonths to tighten or loosen. Default response is slim (id, name, current title/school, coach effect, overlap). Pass full=true to get the full StaffMember payload per node (bios, compensation snapshot, etc.) — large. Response includes a top-level `sources` array of {kind,label,url} links into the ADvantage web app. Cite them as reference footnotes beneath your answer. For the dedicated demo account, only five sample workflows are available. Results are synthetic; sources reference MCP demo resources rather than production web pages.

Given an anchor coach (staff member ID), return the model's nearest neighbors — coaches in the same sport(s) with a similar coach-effect score. Optionally restrict to the same conference. Use when the user asks: - "Find me coaches like Kalen DeBoer for our open job." - "Who are realistic comps for hiring against Lane Kiffin?" - "Show me the market for coaches similar to ours." The anchor's sport(s) are inferred from their profile automatically. Coach effect must exist on the anchor (otherwise the response will be empty with a "no valid coach effect" message). variance defines the coach-effect window: comparables are returned with CE between (anchor_CE - variance) and (anchor_CE + variance). Default 0.5. Allowed 0.25 to 3.0. limit is the page size (max 50). offset is the page offset. conferenceOnly=true restricts results to the anchor's conference. includeMarketValueFallback=true admits coaches without an actual contract on file by their model-predicted market value. Default response is slim. Pass full=true to get rich StaffMember per row. Response includes a top-level `sources` array of {kind,label,url} links into the ADvantage web app. Cite them as reference footnotes beneath your answer. For the dedicated demo account, only five sample workflows are available. Results are synthetic; sources reference MCP demo resources rather than production web pages.

Batch version of staff_compensationHistory. Fetch compensation histories for up to 25 staff members in one MCP call, with an optional university filter per person. Results preserve request order and isolate per-person errors. Use this whenever research requires compensation or appointment evidence for two or more people. Do not loop over staff_compensationHistory sequentially. The default slim response omits contract markdown; full=true can be very large. Response includes a top-level `sources` array of {kind,label,url} links into the ADvantage web app. Cite them as reference footnotes beneath your answer. For the dedicated demo account, only five sample workflows are available. Results are synthetic; sources reference MCP demo resources rather than production web pages.

Return the multi-year compensation record set for one coach — every appointment, every contract component (base, supplemental, incentive, buyout, perk, retention bonus, etc.), and every term within each component. Escalators appear as multiple BASE terms with different effective dates. BUYOUT components identify the direction in buyoutSide. For v2 records, read each term's buyoutTerms: conditionLabel identifies the future, buyoutWindows contains its dated schedule, and each window has one or more buyoutFormula entries. The legacy flat buyout fields are null on v2 terms. Use when the user asks: - "How has Kalen DeBoer's salary changed year-over-year?" - "What's the buyout schedule on this coach's contract?" - "Show me every component of this coach's comp." By default returns a slim shape (drops full contract markdown to keep responses small). Pass full=true to get contract-text-included responses (large; use sparingly). universityId is optional — omit it to get the coach's full career across every school. Pass it to restrict to one university's appointment. For two or more staff members, use staff_compensationHistories instead of calling this tool repeatedly. Response includes a top-level `sources` array of {kind,label,url} links into the ADvantage web app. Cite them as reference footnotes beneath your answer. For the dedicated demo account, only five sample workflows are available. Results are synthetic; sources reference MCP demo resources rather than production web pages.

Given two coaches (A and B), return their shared career history: every other staff member who overlapped BOTH of them at the same university during the same time span, with the overlap windows enumerated per connection. Use when the user asks: - "What's the connection between Kalen DeBoer and Ryan Grubb?" - "Did these two coaches ever work at the same school together?" - "Who do they have in common from their coaching staffs?" By default returns slim matchingStaff DTOs (id, name, current title/school) and the full connections array. Pass full=true to get the rich StaffMember payload per matching staff (bios, compensation snapshot, etc.). Response includes a top-level `sources` array of {kind,label,url} links into the ADvantage web app. Cite them as reference footnotes beneath your answer. For the dedicated demo account, only five sample workflows are available. Results are synthetic; sources reference MCP demo resources rather than production web pages.

Return the education history for one coach, grouped by degree level: - bachelor[], master[], doctorate[], medical[], other[] Each entry carries graduationYear, degree, universityId, universityName. Use when the user asks: - "Where did this coach go to school?" - "What's her academic background?" - "Did this coach attend the school he's coaching at now?" Response includes a top-level `sources` array of {kind,label,url} links into the ADvantage web app. Cite them as reference footnotes beneath your answer. For the dedicated demo account, only five sample workflows are available. Results are synthetic; sources reference MCP demo resources rather than production web pages.

Return the FOIA (Freedom of Information Act) request history for one staff member. Each entry surfaces public-records requests where this coach is a referenced party. Use when the user asks: - "What FOIA requests are on file for this coach?" - "Has anyone submitted public-records requests about her?" - "FOIA coverage on this person." Response includes a top-level `sources` array of {kind,label,url} links into the ADvantage web app. Cite them as reference footnotes beneath your answer. For the dedicated demo account, only five sample workflows are available. Results are synthetic; sources reference MCP demo resources rather than production web pages.

Fetch staff members by their staff member IDs. Returns the same row shape as staff_search(full=true) rows (coach effect, compensation, market value, sport assignments, university affiliation, etc.), excluding structured email and phone fields — but for explicitly-supplied IDs. Use this when you already have one or more staff member IDs and want the current attributes for those specific people. For attribute-based discovery (by name, sport, university, etc.), use staff_search. Response includes a top-level `sources` array with links to each staff member's profile page on the ADvantage web app. It is attached centrally — see src/tool-sources.ts. Response includes a top-level `sources` array of {kind,label,url} links into the ADvantage web app. Cite them as reference footnotes beneath your answer. For the dedicated demo account, only five sample workflows are available. Results are synthetic; sources reference MCP demo resources rather than production web pages.

Fetch the full briefing blob for one staff member — name, title, school, conference, sport assignments, bio, accomplishments, compensation snapshot, market value, and the coach's full career history (every appointment with start/end dates, titles, and schools). Accomplishments match the profile's Accomplishments tab: one entry per accomplishment type — category, name, occurrences, and each occurrence's year, detail, numeric value, and university — ordered most prestigious first. Use when the user asks: - "Give me a briefing on Kalen DeBoer." - "Tell me about this coach." - "Show me everything we know about staff member X." For a list of coaches or attribute-based discovery, use staff_search instead. Response includes a top-level `sources` array of {kind,label,url} links into the ADvantage web app. Cite them as reference footnotes beneath your answer. For the dedicated demo account, only five sample workflows are available. Results are synthetic; sources reference MCP demo resources rather than production web pages.

Return summary stats for a coaching program at one university: - coachCount: how many coaching-category staff are at this university (optionally scoped to a single sport) - playersReceivingAid: latest FRS-reported athletic-aid headcount for the supplied sport (null when sportId is omitted) Use when the user asks: - "How big is Alabama's football coaching staff?" - "How many football scholarship athletes does Alabama report?" - "Quick program-size snapshot." This returns counts only, NOT the list of coaches themselves. For the full roster, use staff_search with universityIds + sportIds + categoryIds=[20]. Response includes a top-level `sources` array of {kind,label,url} links into the ADvantage web app. Cite them as reference footnotes beneath your answer. For the dedicated demo account, only five sample workflows are available. Results are synthetic; sources reference MCP demo resources rather than production web pages.

Search ADVantage's D1 staff directory. Returns paginated coach/admin records with coach effect (performance score), most-recent compensation totals, model-predicted market value, sport assignments, and university/conference affiliation. Use when the user asks about: - Specific coaches by name or attribute ("who's the highest-paid head coach in the SEC") - Filtering staff by sport, title (role), university, or conference - Coach effect (performance) range queries ("coaches above the 90th percentile") - Compensation range queries ("head coaches making more than $5M") - Market-value vs actual-comp gaps Defaults to no filter — pass at least one to get meaningful results. By default the search is NOT scoped to the caller's university (unlike guarantees_search/frs_summary); pass universityIds or conferenceIds explicitly to scope. Response is SLIM by default (id, name, title, affiliation, coach effect, most-recent comp totals, market value summary). Pass full=true to get rich staff details per row, excluding structured email and phone fields — but keep limit low (≤10) when you do, or you'll hit response-size limits. Known V1 gaps (will be fixed in follow-up PRs): - Baseline-improvement score filter not yet supported (DB-repo extension pending). - Employment status filter not yet supported (same blocker). Response includes a top-level `sources` array of {kind,label,url} links into the ADvantage web app. Cite them as reference footnotes beneath your answer. For the dedicated demo account, only five sample workflows are available. Results are synthetic; sources reference MCP demo resources rather than production web pages.

Return per-sport coach-effect rankings for one coach. For each sport the coach participates in, returns: - coachEffect (the score) - rank (their position among all coaches in that sport) - totalCoaches (population size) - percentile (0-100) Use when the user asks: - "How does she rank in basketball specifically?" - "Where does this coach sit among football head coaches?" - "Per-sport rank breakdown for multi-sport coaches." Response includes a top-level `sources` array of {kind,label,url} links into the ADvantage web app. Cite them as reference footnotes beneath your answer. For the dedicated demo account, only five sample workflows are available. Results are synthetic; sources reference MCP demo resources rather than production web pages.

Return per-sport performance series for one coach. Each StatSeries carries a label, a stat key, and an array of StatDataPoint entries with {season, value, rank, university, sportId}. The response also carries which schools the coach was at per season, their titles per season, and head-coaching status per season. Use when the user asks: - "What's Kane Wommack's defensive performance history?" - "Show me Kalen DeBoer's win record across his career." - "Compare two coaches' conference standings over time." By default returns the full response. Pass slim=true to drop statDefinitions and statKeyMetadata (useful when you only need the raw time series). sportIds is optional — omit for all sports the coach has worked in. Response includes a top-level `sources` array of {kind,label,url} links into the ADvantage web app. Cite them as reference footnotes beneath your answer. For the dedicated demo account, only five sample workflows are available. Results are synthetic; sources reference MCP demo resources rather than production web pages.

Return the caller's resolved Customer User identity: Customer, effective university, conference, and staff member. Use this to answer questions about "my school", "my conference", "who am I", or to discover the default scope tools like guarantees_search and frs_summary will use when no explicit IDs are passed. Response includes a top-level `sources` array of {kind,label,url} links into the ADvantage web app. Cite them as reference footnotes beneath your answer. For the dedicated demo account, only five sample workflows are available. Results are synthetic; sources reference MCP demo resources rather than production web pages.