college-scorecard-mcp-server

Search Programs

scorecard_search_programs

Read-only

Find programs across institutions, ranked and filtered by completion-based one-year median earnings within the fetched school page. Legacy highest-credential values remain separate with their own provenance. Earnings and debt pool across campuses sharing OPEID6 within CIP/credential; awards are campus-specific. School page/per_page/total count schools; limit/offset page the matching program rows. Follow next to drain this school page before advancing to the next school page. Use scorecard_lookup_cip to find CIP codes.

Input Schema

Name	Required	Description
`page`	No	Zero-indexed page number.
`limit`	No	Program rows per response; values above 100 normalize to 100.
`state`	No	Comma-separated two-letter state codes; case and whitespace normalized, blanks unset.
`offset`	No	Zero-based row offset within the filtered and sorted school page.
`cip_code`	No	CIP 4-digit code to search for (e.g. "11.07" for Computer Science). Use scorecard_lookup_cip to find codes.
`max_debt`	No	Maximum median cumulative Stafford/Grad PLUS debt across institutions at the same academic level, inclusive; excludes unavailable debt.
`per_page`	No	Schools per page (max 100); program rows may exceed this count.
`ownership`	No	Restrict to school type: 1=public, 2=private nonprofit, 3=for-profit.
`min_earnings`	No	Minimum completion-based one-year median earnings, inclusive, without legacy fallback; filters this school page locally while school totals remain unchanged.
`program_name`	No	Case-insensitive title substring matched within the fetched school page. Ignored when cip_code is provided; use cip_code for upstream program matching.
`max_net_price`	No	Maximum average net price at the school.
`credential_level`	No	Provider credential selector: 1=undergraduate certificate, 2=associate, 3=bachelor, 4=post-baccalaureate certificate, 5=master, 6=doctoral, 7=first professional, 8=graduate/professional certificate, 99=non-credential; other integer levels may return no matches.

Output Schema

Name	Required	Description
`cap`	No	The effective program row limit that was applied.
`next`	No	Continuation using the same selectors and limits; null when exhausted.
`page`	No	Current page (zero-indexed).
`error`	No	Present when the call failed. Absent on success.
`limit`	No	Effective program row limit, at most 100.
`query`	No	Normalized effective selectors and pagination defaults.
`shown`	No	Program rows returned in this response.
`total`	No	Total schools matching upstream filters, before pagination and local program filtering.
`notice`	No	Recovery hint when no programs match or earnings data is unavailable.
`offset`	No	Effective zero-based row offset within this school page.
`per_page`	No	Results per page used.
`programs`	No	One page of program rows retaining credential identities, stably sorted by completion-based one-year earnings descending, with unavailable current earnings last.
`truncated`	No	True when more program rows or a later school page remain.
`nextOffset`	No	Next row offset on this school page, or null when drained.
`provenance`	No	Dictionary provenance for each distinct program population.
`totalCount`	No	Total schools matching upstream filters, before pagination and local program filtering.
`metric_scope`	No	Aggregation scope within CIP and credential identity.
`schools_shown`	No	Schools returned on this school page.
`total_programs`	No	Matching program rows on the fetched school page before row pagination.
`suppressed_count`	No	Matching programs with confirmed privacy-suppressed legacy highest-credential earnings, before row paging.
`unavailable_count`	No	Matching programs with unavailable legacy highest-credential earnings of unknown cause, before row paging.

Schema Changelog

Changes observed during successful MCP inspections.

Changed30 schema fields changedNov 3, 2026

addedInput schema / properties / limit

Added value: +{
+  "default": 20,
+  "description": "Program rows per response; values above 100 normalize to 100.",
+  "maximum": 1000,
+  "minimum": 1,
+  "type": "integer"
+}

changedInput schema / properties / min_earnings / description

Previous value: -"Minimum 1-year median earnings, inclusive. Filters this school page locally and excludes unavailable earnings; school totals are unchanged."New value: +"Minimum completion-based one-year median earnings, inclusive, without legacy fallback; filters this school page locally while school totals remain unchanged."

addedInput schema / properties / offset

Added value: +{
+  "default": 0,
+  "description": "Zero-based row offset within the filtered and sorted school page.",
+  "maximum": 9007199254740991,
+  "minimum": 0,
+  "type": "integer"
+}

changedOutput schema / anyOf

Previous value: -[
-  {
-    "not": {
-      "required": [
-        "error"
-      ]
-    },
-    "required": [
-      "total",
-      "page",
-      "per_page",
-      "programs",
-      "total_programs",
-      "suppressed_count",
-      "unavailable_count",
-      "query",
-      "totalCount",
-      "truncated",
-      "shown",
-      "cap"
-    ]
-  },
-  {
-    "required": [
-      "error"
-    ]
-  }
-]New value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "metric_scope",
+      "provenance",
+      "shown",
+      "offset",
+      "limit",
+      "nextOffset",
+      "next",
+      "total",
+      "page",
+      "per_page",
+      "programs",
+      "total_programs",
+      "suppressed_count",
+      "unavailable_count",
+      "query",
+      "totalCount",
+      "truncated",
+      "schools_shown",
+      "cap"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

changedOutput schema / properties / cap / description

Previous value: -"The per_page limit that was applied."New value: +"The effective program row limit that was applied."

addedOutput schema / properties / limit

Added value: +{
+  "description": "Effective program row limit, at most 100.",
+  "type": "number"
+}

addedOutput schema / properties / metric_scope

Added value: +{
+  "additionalProperties": false,
+  "description": "Aggregation scope within CIP and credential identity.",
+  "properties": {
+    "debt": {
+      "const": "opeid6",
+      "description": "Debt pools across campuses sharing OPEID6.",
+      "type": "string"
+    },
+    "earnings": {
+      "const": "opeid6",
+      "description": "Earnings pool across campuses sharing OPEID6.",
+      "type": "string"
+    },
+    "ipeds_awards": {
+      "const": "campus",
+      "description": "Awards belong to the campus.",
+      "type": "string"
+    },
+    "program_identity": {
+      "description": "Program dimensions retained within each pooled group.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "earnings",
+    "debt",
+    "ipeds_awards",
+    "program_identity"
+  ],
+  "type": "object"
+}

addedOutput schema / properties / next

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "properties": {
+        "offset": {
+          "description": "Row offset to request on that school page.",
+          "type": "number"
+        },
+        "page": {
+          "description": "School page to request.",
+          "type": "number"
+        }
+      },
+      "required": [
+        "page",
+        "offset"
+      ],
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Continuation using the same selectors and limits; null when exhausted."
+}

addedOutput schema / properties / nextOffset

Added value: +{
+  "description": "Next row offset on this school page, or null when drained.",
+  "type": [
+    "number",
+    "null"
+  ]
+}

addedOutput schema / properties / offset

Added value: +{
+  "description": "Effective zero-based row offset within this school page.",
+  "type": "number"
+}

changedOutput schema / properties / programs / description

Previous value: -"Program rows retain separate credential identities, sorted by earnings descending with unavailable or privacy-suppressed earnings last."New value: +"One page of program rows retaining credential identities, stably sorted by completion-based one-year earnings descending, with unavailable current earnings last."

addedOutput schema / properties / programs / items / properties / completion_1yr_availability

Added value: +{
+  "description": "Availability of completion-based one-year median earnings.",
+  "enum": [
+    "available",
+    "unavailable",
+    "privacy_suppressed"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / programs / items / properties / completion_1yr_count

Added value: +{
+  "description": "Working and not enrolled completers in the one-year earnings population.",
+  "type": "number"
+}

addedOutput schema / properties / programs / items / properties / completion_1yr_count_availability

Added value: +{
+  "description": "Availability of the matching one-year population count.",
+  "enum": [
+    "available",
+    "unavailable",
+    "privacy_suppressed"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / programs / items / properties / completion_1yr_median

Added value: +{
+  "description": "Median earnings one year after completion, in the stated dollar year.",
+  "type": "number"
+}

addedOutput schema / properties / programs / items / properties / completion_4yr_availability

Added value: +{
+  "description": "Availability of completion-based four-year median earnings.",
+  "enum": [
+    "available",
+    "unavailable",
+    "privacy_suppressed"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / programs / items / properties / completion_4yr_count

Added value: +{
+  "description": "Working and not enrolled completers in the four-year earnings population.",
+  "type": "number"
+}

addedOutput schema / properties / programs / items / properties / completion_4yr_count_availability

Added value: +{
+  "description": "Availability of the matching four-year population count.",
+  "enum": [
+    "available",
+    "unavailable",
+    "privacy_suppressed"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / programs / items / properties / completion_4yr_median

Added value: +{
+  "description": "Median earnings four years after completion, in the stated dollar year.",
+  "type": "number"
+}

addedOutput schema / properties / programs / items / properties / earnings_count

Added value: +{
+  "description": "Legacy highest-credential working/not-enrolled population count.",
+  "type": "number"
+}

addedOutput schema / properties / programs / items / properties / earnings_count_availability

Added value: +{
+  "description": "Availability of the legacy highest-credential count.",
+  "enum": [
+    "available",
+    "unavailable",
+    "privacy_suppressed"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / programs / items / properties / ope6_id

Added value: +{
+  "description": "Provider OPEID6 group identifier, preserving leading zeros; null when absent.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

changedOutput schema / properties / programs / items / required

Previous value: -[
-  "school_id",
-  "school_name",
-  "school_ownership",
-  "program_code",
-  "suppressed",
-  "earnings_availability"
-]New value: +[
+  "completion_1yr_availability",
+  "completion_1yr_count_availability",
+  "completion_4yr_availability",
+  "completion_4yr_count_availability",
+  "ope6_id",
+  "earnings_count_availability",
+  "school_id",
+  "school_name",
+  "school_ownership",
+  "program_code",
+  "suppressed",
+  "earnings_availability"
+]

addedOutput schema / properties / provenance

Added value: +{
+  "additionalProperties": false,
+  "description": "Dictionary provenance for each distinct program population.",
+  "properties": {
+    "completion_1yr": {
+      "additionalProperties": false,
+      "description": "Current completion-based one-year series.",
+      "properties": {
+        "cohort": {
+          "description": "Pooled completion academic years.",
+          "items": {
+            "description": "Academic year.",
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "count_cell": {
+          "description": "Most-recent count map cell.",
+          "type": "string"
+        },
+        "count_variable": {
+          "description": "Dictionary count variable.",
+          "type": "string"
+        },
+        "dollar_year": {
+          "description": "Inflation-adjusted dollar year.",
+          "type": "number"
+        },
+        "measurement_years": {
+          "description": "Earnings measurement calendar years.",
+          "items": {
+            "description": "Calendar year.",
+            "type": "number"
+          },
+          "type": "array"
+        },
+        "median_cell": {
+          "description": "Most-recent median map cell.",
+          "type": "string"
+        },
+        "median_variable": {
+          "description": "Dictionary median variable.",
+          "type": "string"
+        },
+        "population": {
+          "description": "Population represented.",
+          "type": "string"
+        }
+      },
+      "required": [
+        "cohort",
+        "measurement_years",
+        "dollar_year",
+        "median_variable",
+        "count_variable",
+        "median_cell",
+        "count_cell",
+        "population"
+      ],
+      "type": "object"
+    },
+    "completion_4yr": {
+      "additionalProperties": false,
+      "description": "Current completion-based four-year series.",
+      "properties": {
+        "cohort": {
+          "description": "Pooled completion academic years.",
+          "items": {
+            "description": "Academic year.",
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "count_cell": {
+          "description": "Most-recent count map cell.",
+          "type": "string"
+        },
+        "count_variable": {
+          "description": "Dictionary count variable.",
+          "type": "string"
+        },
+        "dollar_year": {
+          "description": "Inflation-adjusted dollar year.",
+          "type": "number"
+        },
+        "measurement_years": {
+          "description": "Earnings measurement calendar years.",
+          "items": {
+            "description": "Calendar year.",
+            "type": "number"
+          },
+          "type": "array"
+        },
+        "median_cell": {
+          "description": "Most-recent median map cell.",
+          "type": "string"
+        },
+        "median_variable": {
+          "description": "Dictionary median variable.",
+          "type": "string"
+        },
+        "population": {
+          "description": "Population represented.",
+          "type": "string"
+        }
+      },
+      "required": [
+        "cohort",
+        "measurement_years",
+        "dollar_year",
+        "median_variable",
+        "count_variable",
+        "median_cell",
+        "count_cell",
+        "population"
+      ],
+      "type": "object"
+    },
+    "debt": {
+      "additionalProperties": false,
+      "description": "Debt provenance distinct from earnings.",
+      "properties": {
+        "cell": {
+          "description": "Most-recent map cell.",
+          "type": "string"
+        },
+        "cohort": {
+          "description": "Pooled debt academic years.",
+          "items": {
+            "description": "Academic year.",
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "population": {
+          "description": "Borrower population.",
+          "type": "string"
+        },
+        "variable": {
+          "description": "Dictionary variable.",
+          "type": "string"
+        }
+      },
+      "required": [
+        "cohort",
+        "variable",
+        "cell",
+        "population"
+      ],
+      "type": "object"
+    },
+    "highest_credential_1yr": {
+      "additionalProperties": false,
+      "description": "Legacy highest-credential series.",
+      "properties": {
+        "cohort": {
+          "description": "Pooled completion academic years.",
+          "items": {
+            "description": "Academic year.",
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "count_cell": {
+          "description": "Most-recent count map cell.",
+          "type": "string"
+        },
+        "count_variable": {
+          "description": "Dictionary count variable.",
+          "type": "string"
+        },
+        "dollar_year": {
+          "description": "Inflation-adjusted dollar year.",
+          "type": "number"
+        },
+        "measurement_years": {
+          "description": "Earnings measurement calendar years.",
+          "items": {
+            "description": "Calendar year.",
+            "type": "number"
+          },
+          "type": "array"
+        },
+        "median_cell": {
+          "description": "Most-recent median map cell.",
+          "type": "string"
+        },
+        "median_variable": {
+          "description": "Dictionary median variable.",
+          "type": "string"
+        },
+        "population": {
+          "description": "Population represented.",
+          "type": "string"
+        }
+      },
+      "required": [
+        "cohort",
+        "measurement_years",
+        "dollar_year",
+        "median_variable",
+        "count_variable",
+        "median_cell",
+        "count_cell",
+        "population"
+      ],
+      "type": "object"
+    },
+    "ipeds_awards_year1": {
+      "additionalProperties": false,
+      "description": "First debt-cohort year awards.",
+      "properties": {
+        "academic_year": {
+          "description": "Academic year of awards.",
+          "type": "string"
+        },
+        "cell": {
+          "description": "Most-recent map cell.",
+          "type": "string"
+        },
+        "population": {
+          "description": "Awards population.",
+          "type": "string"
+        },
+        "variable": {
+          "description": "Dictionary variable.",
+          "type": "string"
+        }
+      },
+      "required": [
+        "academic_year",
+        "variable",
+        "cell",
+        "population"
+      ],
+      "type": "object"
+    },
+    "ipeds_awards_year2": {
+      "additionalProperties": false,
+      "description": "Second debt-cohort year awards.",
+      "properties": {
+        "academic_year": {
+          "description": "Academic year of awards.",
+          "type": "string"
+        },
+        "cell": {
+          "description": "Most-recent map cell.",
+          "type": "string"
+        },
+        "population": {
+          "description": "Awards population.",
+          "type": "string"
+        },
+        "variable": {
+          "description": "Dictionary variable.",
+          "type": "string"
+        }
+      },
+      "required": [
+        "academic_year",
+        "variable",
+        "cell",
+        "population"
+      ],
+      "type": "object"
+    },
+    "source": {
+      "description": "Official dictionary URL.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "source",
+    "highest_credential_1yr",
+    "completion_1yr",
+    "completion_4yr",
+    "debt",
+    "ipeds_awards_year1",
+    "ipeds_awards_year2"
+  ],
+  "type": "object"
+}

addedOutput schema / properties / schools_shown

Added value: +{
+  "description": "Schools returned on this school page.",
+  "type": "number"
+}

changedOutput schema / properties / shown / description

Previous value: -"Schools returned on this page."New value: +"Program rows returned in this response."

changedOutput schema / properties / suppressed_count / description

Previous value: -"Programs with suppressed earnings."New value: +"Matching programs with confirmed privacy-suppressed legacy highest-credential earnings, before row paging."

changedOutput schema / properties / total_programs / description

Previous value: -"Total programs returned across all result schools."New value: +"Matching program rows on the fetched school page before row pagination."

changedOutput schema / properties / truncated / description

Previous value: -"True when school pagination metadata indicates a later page exists."New value: +"True when more program rows or a later school page remain."

changedOutput schema / properties / unavailable_count / description

Previous value: -"Programs with unavailable earnings of unknown cause."New value: +"Matching programs with unavailable legacy highest-credential earnings of unknown cause, before row paging."

Changed9 schema fields changedOct 14, 2026

addedInput schema / properties / credential_level

Added value: +{
+  "description": "Provider credential selector: 1=undergraduate certificate, 2=associate, 3=bachelor, 4=post-baccalaureate certificate, 5=master, 6=doctoral, 7=first professional, 8=graduate/professional certificate, 99=non-credential; other integer levels may return no matches.",
+  "maximum": 9007199254740991,
+  "minimum": -9007199254740991,
+  "type": "integer"
+}

changedOutput schema / anyOf

Previous value: -[
-  {
-    "not": {
-      "required": [
-        "error"
-      ]
-    },
-    "required": [
-      "total",
-      "page",
-      "per_page",
-      "programs",
-      "total_programs",
-      "suppressed_count",
-      "query",
-      "totalCount",
-      "truncated",
-      "shown",
-      "cap"
-    ]
-  },
-  {
-    "required": [
-      "error"
-    ]
-  }
-]New value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "total",
+      "page",
+      "per_page",
+      "programs",
+      "total_programs",
+      "suppressed_count",
+      "unavailable_count",
+      "query",
+      "totalCount",
+      "truncated",
+      "shown",
+      "cap"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

changedOutput schema / properties / programs / description

Previous value: -"Program results — multiple programs per school if school matches multiple CIP codes. Sorted by earnings descending (suppressed last)."New value: +"Program rows retain separate credential identities, sorted by earnings descending with unavailable or privacy-suppressed earnings last."

addedOutput schema / properties / programs / items / properties / credential_level

Added value: +{
+  "description": "Provider credential level; unknown future numeric levels are retained.",
+  "maximum": 9007199254740991,
+  "minimum": -9007199254740991,
+  "type": "integer"
+}

addedOutput schema / properties / programs / items / properties / credential_title

Added value: +{
+  "description": "Provider credential title, when reported.",
+  "type": "string"
+}

addedOutput schema / properties / programs / items / properties / earnings_availability

Added value: +{
+  "description": "Available number, unavailable with unknown cause, or confirmed privacy suppression.",
+  "enum": [
+    "available",
+    "unavailable",
+    "privacy_suppressed"
+  ],
+  "type": "string"
+}

changedOutput schema / properties / programs / items / properties / suppressed / description

Previous value: -"True when earnings are suppressed due to small cohort."New value: +"True only for explicit provider privacy markers."

changedOutput schema / properties / programs / items / required

Previous value: -[
-  "school_id",
-  "school_name",
-  "school_ownership",
-  "program_code",
-  "suppressed"
-]New value: +[
+  "school_id",
+  "school_name",
+  "school_ownership",
+  "program_code",
+  "suppressed",
+  "earnings_availability"
+]

addedOutput schema / properties / unavailable_count

Added value: +{
+  "description": "Programs with unavailable earnings of unknown cause.",
+  "type": "number"
+}

First observedOct 13, 2026

TDQS

A3.8/5.0

Behavior4/5

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

Annotations only declare readOnlyHint and openWorldHint; the description adds substantial non-obvious behavior — earnings/debt pool across campuses sharing OPEID6 while awards are campus-specific, legacy credential values carry separate provenance, and min_earnings filters only the local school page without changing school totals. It stops short of noting rate limits or output shape, but this is well beyond what the annotations convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded and every sentence carries information, but some phrasing is terse to the point of opacity ('Legacy highest-credential values remain separate with their own provenance') and the pagination-tier sentence is dense. No filler, though it could be ordered more cleanly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 12-parameter tool with an output schema, the description covers the genuinely hard parts: two-tier pagination, cross-campus pooling, and local filtering semantics. The main remaining gap is sibling disambiguation against scorecard_get_programs and scorecard_search_schools, which an agent would still have to guess.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning the schema does not: it explains that page/per_page/total govern the school tier while limit/offset page the matching program rows within that tier, which is essential to using 12 parameters correctly. The 'without legacy fallback' note on min_earnings also clarifies a subtlety the schema only hints at.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Find programs across institutions, ranked and filtered by completion-based one-year median earnings'), so the agent knows exactly what the tool returns. It does not distinguish itself from the sibling scorecard_get_programs, which is the closest-looking alternative, so it falls short of a 5.

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

Usage Guidelines3/5

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

Provides two concrete usage instructions: use scorecard_lookup_cip to resolve CIP codes, and follow 'next' to drain a school page before advancing. However, it never says when to prefer this over scorecard_get_programs or scorecard_search_schools, so the core selection decision is left to inference.

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

All college-scorecard-mcp-server tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.