college-scorecard-mcp-server

Get School Programs

scorecard_get_programs

Read-onlyIdempotent

Page through field-of-study programs at one school, ranked and filtered by completion-based one-year earnings. Legacy highest-credential earnings remain separate from current one- and four-year completion series, with dictionary provenance. Earnings and debt pool across campuses sharing OPEID6 within CIP/credential; awards are campus-specific. Use scorecard_lookup_cip to find CIP codes by name.

Input Schema

Name	Required	Description
`id`	Yes	School ID from scorecard_search_schools.
`limit`	No	Program rows per response; values above 100 normalize to 100.
`offset`	No	Zero-based program row offset after filtering and stable earnings ordering.
`cip_code`	No	Filter to one 4-digit CIP code, dotted or undotted (e.g. "11.07" or "1107" for Computer Science). Returns one row per credential level the school offers in that program.
`min_earnings`	No	Minimum completion-based one-year median earnings; no legacy fallback.
`credential_level`	No	Filter by credential level: 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.

Output Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`limit`	No	Effective program row limit, at most 100.
`query`	No	Normalized effective school ID and program selectors.
`shown`	No	Program rows returned on this page.
`total`	No	Total matching programs before row pagination.
`notice`	No	Guidance when no programs match or some earnings are unavailable or privacy-suppressed.
`offset`	No	Effective zero-based program offset.
`ope6_id`	No	Provider OPEID6 group identifier, preserving leading zeros; null when absent.
`programs`	No	One page of matching programs, stably sorted by completion-based one-year earnings descending, with unavailable current earnings last.
`school_id`	No	School unit ID.
`truncated`	No	More matching program rows remain.
`nextOffset`	No	Next program row offset, or null when exhausted.
`provenance`	No	Dictionary cohort, measurement, and dollar provenance for each population.
`school_name`	No	Institution name.
`metric_scope`	No	Metric aggregation scope within CIP and credential.
`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.

Changed28 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 post-graduation median earnings filter."New value: +"Minimum completion-based one-year median earnings; no legacy fallback."

addedInput schema / properties / offset

Added value: +{
+  "default": 0,
+  "description": "Zero-based program row offset after filtering and stable earnings ordering.",
+  "maximum": 9007199254740991,
+  "minimum": 0,
+  "type": "integer"
+}

changedOutput schema / anyOf

Previous value: -[
-  {
-    "not": {
-      "required": [
-        "error"
-      ]
-    },
-    "required": [
-      "school_id",
-      "school_name",
-      "programs",
-      "total",
-      "suppressed_count",
-      "unavailable_count",
-      "query"
-    ]
-  },
-  {
-    "required": [
-      "error"
-    ]
-  }
-]New value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "ope6_id",
+      "metric_scope",
+      "provenance",
+      "shown",
+      "offset",
+      "limit",
+      "nextOffset",
+      "truncated",
+      "school_id",
+      "school_name",
+      "programs",
+      "total",
+      "suppressed_count",
+      "unavailable_count",
+      "query"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

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": "Metric aggregation scope within CIP and credential.",
+  "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 / nextOffset

Added value: +{
+  "description": "Next program row offset, or null when exhausted.",
+  "type": [
+    "number",
+    "null"
+  ]
+}

addedOutput schema / properties / offset

Added value: +{
+  "description": "Effective zero-based program offset.",
+  "type": "number"
+}

addedOutput schema / properties / ope6_id

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

changedOutput schema / properties / programs / description

Previous value: -"All programs matching the filters, sorted by earnings descending with unavailable or privacy-suppressed earnings last."New value: +"One page of matching programs, 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 / credential_level_code

Added value: +{
+  "description": "Provider numeric credential identity; the legacy credential_level field remains a display label.",
+  "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_count_availability

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

changedOutput schema / properties / programs / items / required

Previous value: -[
-  "code",
-  "credential_level",
-  "suppressed",
-  "earnings_availability"
-]New value: +[
+  "completion_1yr_availability",
+  "completion_1yr_count_availability",
+  "completion_4yr_availability",
+  "completion_4yr_count_availability",
+  "earnings_count_availability",
+  "code",
+  "credential_level",
+  "suppressed",
+  "earnings_availability"
+]

addedOutput schema / properties / provenance

Added value: +{
+  "additionalProperties": false,
+  "description": "Dictionary cohort, measurement, and dollar provenance for each 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 / shown

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

changedOutput schema / properties / suppressed_count / description

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

changedOutput schema / properties / total / description

Previous value: -"Total programs returned after filtering."New value: +"Total matching programs before row pagination."

addedOutput schema / properties / truncated

Added value: +{
+  "description": "More matching program rows remain.",
+  "type": "boolean"
+}

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."

Changed8 schema fields changedOct 14, 2026

changedOutput schema / anyOf

Previous value: -[
-  {
-    "not": {
-      "required": [
-        "error"
-      ]
-    },
-    "required": [
-      "school_id",
-      "school_name",
-      "programs",
-      "total",
-      "suppressed_count",
-      "query"
-    ]
-  },
-  {
-    "required": [
-      "error"
-    ]
-  }
-]New value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "school_id",
+      "school_name",
+      "programs",
+      "total",
+      "suppressed_count",
+      "unavailable_count",
+      "query"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

changedOutput schema / properties / notice / description

Previous value: -"Guidance when no programs match the filters or all data is suppressed."New value: +"Guidance when no programs match or some earnings are unavailable or privacy-suppressed."

changedOutput schema / properties / programs / description

Previous value: -"All programs at this school matching the filters. Sorted by median earnings descending (suppressed programs at end)."New value: +"All programs matching the filters, sorted by earnings descending with unavailable or privacy-suppressed earnings last."

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 data is suppressed due to small cohort (FERPA)."New value: +"True only when the provider explicitly marks earnings as privacy-suppressed."

changedOutput schema / properties / programs / items / required

Previous value: -[
-  "code",
-  "credential_level",
-  "suppressed"
-]New value: +[
+  "code",
+  "credential_level",
+  "suppressed",
+  "earnings_availability"
+]

changedOutput schema / properties / suppressed_count / description

Previous value: -"Number of programs with earnings suppressed due to small cohort."New value: +"Number of programs with confirmed privacy-suppressed earnings."

addedOutput schema / properties / unavailable_count

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

First observedOct 13, 2026

TDQS

A3.9/5.0

Behavior5/5

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

Beyond the readOnlyHint/openWorldHint/idempotentHint annotations, the description discloses important data behavior: legacy highest-credential earnings are separate from current completion series, earnings and debt pool across campuses sharing OPEID6 within CIP/credential, and awards remain campus-specific. These caveats materially affect interpretation of the results.

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?

The description is front-loaded with the core action and then layers in relevant caveats without filler. It is somewhat dense, especially 'dictionary provenance,' but every sentence contributes useful context.

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?

Given the full input schema, output schema, and annotations, the definition covers the essential data semantics an agent needs for correct interpretation. The main remaining gap is explicit routing against sibling program-search tools, but the core behavior is otherwise well specified.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents all six parameters, including CIP format, credential levels, and offset behavior. The description reinforces the completion-based earnings filter and points to CIP lookup, but adds little parameter-level meaning beyond the schema.

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?

The description states a specific action and resource: 'Page through field-of-study programs at one school,' with scope 'ranked and filtered by completion-based one-year earnings.' This is clear, but it does not explicitly distinguish this tool from sibling scorecard_search_programs except through the 'one school' constraint.

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?

It gives a useful pointer to scorecard_lookup_cip for finding CIP codes, which clarifies one supporting workflow. However, it does not say when to use this tool versus scorecard_search_programs or scorecard_get_earnings, and it provides no explicit exclusions.

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.