Tools

9 tools for working with U.S. Department of Education College Scorecard data — institution search, program-level earnings, cost and outcomes analysis, and structured comparison:

scorecard_search_schools

Search for institutions using name, location, and institutional filters.

• Free-text name search plus typed filters: state, ownership (public/private nonprofit/private for-profit), degree level, size range, acceptance rate range
• Geographic proximity filtering by U.S. zip code and distance (miles or km)
• CIP code filter to find schools offering a specific program family
• Pagination (per_page up to 100, zero-indexed page)
• Returns core identity and cost metrics for quick scanning

scorecard_get_school

Fetch a full institutional profile by school ID.

• Accepts a single ID or an array of IDs (batch fetch up to 100 per page)
• Covers costs, admissions, outcomes, financial aid, demographics, and completion rates
• Optional fields override for callers who need a narrower or broader field set
• For side-by-side comparison on a specific dimension, use scorecard_compare_schools

scorecard_compare_schools

Normalized comparison across 2–5 institutions on a named topic.

• Four topics: costs, admissions, outcomes, aid — each pulls a curated topic-specific field set
• Computes within-set percentile ranks and relative deltas — structured output an agent cannot reconstruct from raw profiles
• Single API call for all schools; normalization applied post-fetch
• Distinct from scorecard_get_school multi-ID: output shape is rows, not profiles

scorecard_get_programs

List all field-of-study programs at one school with earnings and debt data.

• Returns P25/median/P75 earnings 1 year after graduation, median debt at graduation, and enrollment figures per program
• Filter by CIP code to return only matching programs
• Filter by credential_level (certificate, associate's, bachelor's) and minimum earnings threshold
• Primary source for program-level earnings — institution-level earnings at 6/8/10 years are available via scorecard_get_earnings
• FERPA suppression surfaced as structured suppressed: true flag with suppression_note, not bare null

scorecard_search_programs

Find programs by CIP code or name across all institutions, ranked by median earnings.

• Program-centric: "which schools in Washington have CS programs with median earnings over $80k?"
• Accepts school-side filters: state, ownership, max net price
• Earnings and debt thresholds for filtering results
• Returns school name, school ID, and unit ID alongside program metrics for follow-up chaining
• Sorting applied post-fetch where earnings fields are not API-indexed

scorecard_get_earnings

Institution-level post-graduation earnings for one school.

• Median and P25/P75 earnings at 6, 8, and 10 years after entry
• Optional gender breakdown when available
• years parameter for time-series analysis; defaults to latest.* for current-state queries
• Reflects outcomes across all graduates, not broken down by program

scorecard_value_analysis

Workflow tool: "Is this school worth it?"

• Parallel-fetches cost/debt/repayment and earnings data in two concurrent requests
• Computes ROI metrics the API does not pre-calculate: debt-to-earnings ratio (median debt / 6-year earnings), net price to first-year earnings ratio, and 3-year loan repayment rate
• family_income parameter selects the applicable net price bracket
• Fetches peer school identifiers (same Carnegie category and ownership) for comparative median values
• Returns all source figures alongside derived metrics — callers can audit the arithmetic
• data_notes flags any suppressed or null fields with structured explanations

scorecard_lookup_cip

Search CIP codes by keyword or partial name.

• Covers the full ~2,400-code CIP taxonomy embedded as static data
• No API call required — zero rate-limit impact, works offline
• Required before using CIP-based filters when the caller knows a program by name but not code
• Returns matching codes with standard titles

scorecard_list_fields

Search the Scorecard field catalog by keyword.

• ~2,800 field entries from the data dictionary, embedded as static data
• Returns field paths, descriptions, data types, and whether the field supports API-side sorting
• No API call required — zero rate-limit impact
• Use before passing custom fields parameters to search/get tools

Resources and prompts

All resource data is also reachable via tools. Use scorecard_search_schools or scorecard_get_school to discover school IDs before constructing resource URIs.

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool, resource, and prompt definitions — single file per primitive, framework handles registration and validation
• Unified error handling — handlers throw, framework catches, classifies, and formats
• Pluggable auth: none, jwt, oauth
• Swappable storage backends: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1
• Structured logging with optional OpenTelemetry tracing
• STDIO and Streamable HTTP transports

College Scorecard-specific: