college-scorecard-mcp-server

Get School Earnings

scorecard_get_earnings

Read-onlyIdempotent

Institution-level earnings of federally aided undergraduate entrants working and not enrolled, regardless of completion. Reports medians at 6/8/10 years after entry, 6/10-year percentiles, and non-male/male 6-year medians. For graduate program earnings use scorecard_get_programs. years selects API data-file start years (1996–2025), including files without earnings observations. Per-metric availability and official cohort/measurement/dollar context accompany values; unknown metadata stays absent. No re-inflation is performed.

Input Schema

Name	Required	Description	Default
`id`	Yes	School ID from scorecard_search_schools.
`years`	No	Optional API data-file start years from 1996–2025 (e.g. [2003, 2011, 2020]); valid files may lack observations. Omit or pass [] for snapshot only.

Output Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`trend`	No	Historical rows by API data-file start year. Present only when nonempty years were supplied.
`current`	No	Most recent available earnings snapshot.
`ope6_id`	No	Provider OPEID6 identifier, preserving leading zeros.
`school_id`	No	School unit ID.
`suppressed`	No	True only when every supported current metric has an explicit privacy marker.
`school_name`	No	Institution name.
`metric_scope`	No	Earnings, debt and repayment are pooled at OPEID6; completion is campus-specific.
`current_context`	No	Official latest provenance keyed by metric, independent of returned values.
`suppression_note`	No	Explains suppression when suppressed=true.
`current_availability`	No	Availability keyed by every supported current earnings metric.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedNov 3, 2026

addedOutput schema / properties / metric_scope

Added value: +{
+  "additionalProperties": false,
+  "description": "Earnings, debt and repayment are pooled at OPEID6; completion is campus-specific.",
+  "properties": {
+    "completion": {
+      "const": "campus",
+      "description": "Completion is campus-specific.",
+      "type": "string"
+    },
+    "debt": {
+      "const": "opeid6",
+      "description": "Debt is OPEID6-pooled.",
+      "type": "string"
+    },
+    "earnings": {
+      "const": "opeid6",
+      "description": "Earnings are OPEID6-pooled.",
+      "type": "string"
+    },
+    "repayment": {
+      "const": "opeid6",
+      "description": "Repayment is OPEID6-pooled.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "earnings",
+    "debt",
+    "repayment",
+    "completion"
+  ],
+  "type": "object"
+}

addedOutput schema / properties / ope6_id

Added value: +{
+  "description": "Provider OPEID6 identifier, preserving leading zeros.",
+  "type": "string"
+}

Changed18 schema fields changedOct 14, 2026

changedInput schema / properties / years / description

Previous value: -"Optional list of cohort entry years for historical trend data (e.g. [2011, 2012, 2013]). Omit for current snapshot."New value: +"Optional API data-file start years from 1996–2025 (e.g. [2003, 2011, 2020]); valid files may lack observations. Omit or pass [] for snapshot only."

addedInput schema / properties / years / items / description

Added value: +"Published API data-file start year (1996–2025)."

changedInput schema / properties / years / items / maximum
```
Previous value: -9007199254740991New value: +2025
```
changedInput schema / properties / years / items / minimum
```
Previous value: --9007199254740991New value: +1996
```

changedOutput schema / anyOf

Previous value: -[
-  {
-    "not": {
-      "required": [
-        "error"
-      ]
-    },
-    "required": [
-      "school_id",
-      "school_name",
-      "current",
-      "suppressed"
-    ]
-  },
-  {
-    "required": [
-      "error"
-    ]
-  }
-]New value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "school_id",
+      "school_name",
+      "current_availability",
+      "current_context",
+      "current",
+      "suppressed"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

removedOutput schema / properties / current / properties / earnings_6yr_female_median

Removed value: -{
-  "description": "Median earnings 6 years after entry for female students.",
-  "type": "number"
-}

addedOutput schema / properties / current / properties / earnings_6yr_non_male_median

Added value: +{
+  "description": "Median earnings 6 years after entry for non-male students.",
+  "type": "number"
+}

addedOutput schema / properties / current_availability

Added value: +{
+  "additionalProperties": {
+    "description": "Provider availability for one supported metric.",
+    "enum": [
+      "available",
+      "unavailable",
+      "privacy_suppressed"
+    ],
+    "type": "string"
+  },
+  "description": "Availability keyed by every supported current earnings metric.",
+  "propertyNames": {
+    "type": "string"
+  },
+  "type": "object"
+}

addedOutput schema / properties / current_context

Added value: +{
+  "additionalProperties": {
+    "additionalProperties": false,
+    "description": "Official provenance for one metric.",
+    "properties": {
+      "data_file_year": {
+        "description": "Start year of the API data file; not a cohort entry year.",
+        "maximum": 9007199254740991,
+        "minimum": -9007199254740991,
+        "type": "integer"
+      },
+      "dollar_year": {
+        "description": "Verified inflation dollar basis; returned values are not re-inflated.",
+        "maximum": 9007199254740991,
+        "minimum": -9007199254740991,
+        "type": "integer"
+      },
+      "entry_cohorts": {
+        "description": "Verified academic-year entry cohorts.",
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "measurement_years": {
+        "description": "Verified calendar years when earnings were measured.",
+        "items": {
+          "maximum": 9007199254740991,
+          "minimum": -9007199254740991,
+          "type": "integer"
+        },
+        "type": "array"
+      }
+    },
+    "required": [
+      "data_file_year"
+    ],
+    "type": "object"
+  },
+  "description": "Official latest provenance keyed by metric, independent of returned values.",
+  "propertyNames": {
+    "type": "string"
+  },
+  "type": "object"
+}

changedOutput schema / properties / suppressed / description

Previous value: -"True when earnings data is suppressed across all time points."New value: +"True only when every supported current metric has an explicit privacy marker."

changedOutput schema / properties / trend / description

Previous value: -"Historical trend rows by cohort entry year. Present only when years parameter was supplied."New value: +"Historical rows by API data-file start year. Present only when nonempty years were supplied."

changedOutput schema / properties / trend / items / description

Previous value: -"Earnings data point for one cohort entry year."New value: +"Earnings observations for one API data file."

addedOutput schema / properties / trend / items / properties / availability

Added value: +{
+  "additionalProperties": {
+    "description": "Provider availability for one supported metric.",
+    "enum": [
+      "available",
+      "unavailable",
+      "privacy_suppressed"
+    ],
+    "type": "string"
+  },
+  "description": "Availability of the supported historical medians.",
+  "propertyNames": {
+    "type": "string"
+  },
+  "type": "object"
+}

addedOutput schema / properties / trend / items / properties / context

Added value: +{
+  "additionalProperties": {
+    "additionalProperties": false,
+    "description": "Official provenance for one metric.",
+    "properties": {
+      "data_file_year": {
+        "description": "Start year of the API data file; not a cohort entry year.",
+        "maximum": 9007199254740991,
+        "minimum": -9007199254740991,
+        "type": "integer"
+      },
+      "dollar_year": {
+        "description": "Verified inflation dollar basis; returned values are not re-inflated.",
+        "maximum": 9007199254740991,
+        "minimum": -9007199254740991,
+        "type": "integer"
+      },
+      "entry_cohorts": {
+        "description": "Verified academic-year entry cohorts.",
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "measurement_years": {
+        "description": "Verified calendar years when earnings were measured.",
+        "items": {
+          "maximum": 9007199254740991,
+          "minimum": -9007199254740991,
+          "type": "integer"
+        },
+        "type": "array"
+      }
+    },
+    "required": [
+      "data_file_year"
+    ],
+    "type": "object"
+  },
+  "description": "Verified per-metric provenance; unknown metadata omitted.",
+  "propertyNames": {
+    "type": "string"
+  },
+  "type": "object"
+}

changedOutput schema / properties / trend / items / properties / earnings_10yr_median / description

Previous value: -"Median earnings 10 years after entry for this cohort."New value: +"Median earnings 10 years after entry reported in this data file."

changedOutput schema / properties / trend / items / properties / earnings_6yr_median / description

Previous value: -"Median earnings 6 years after entry for this cohort."New value: +"Median earnings 6 years after entry reported in this data file."

changedOutput schema / properties / trend / items / properties / year / description
```
Previous value: -"Cohort entry year."New value: +"API data-file start year."
```

changedOutput schema / properties / trend / items / required

Previous value: -[
-  "year"
-]New value: +[
+  "year",
+  "availability",
+  "context"
+]

First observedOct 13, 2026

TDQS

A4.1/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the safety profile is covered; the description adds genuine context beyond that. It warns that years can select data files with no earnings observations, that per-metric availability and official cohort/measurement/dollar framing accompany values, that unknown metadata is omitted rather than inferred, and that no re-inflation is applied — all material to interpreting sparse or missing 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?

Content is front-loaded: what is reported, then the sibling alternative, then parameter and data-quality caveats. Sentences are dense but each carries substantive information; the metric enumeration is long yet necessary to describe the output shape, with only minor redundancy between the description and the schema on years.

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?

An output schema exists, so return values need no explanation, and the description still covers cohort definition, metric set, availability caveats, and sibling routing. What remains thin is edge behavior — e.g., failure modes for invalid ids or how sparse results are represented — leaving it strong but not exhaustive for a read tool with dual id formats.

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 both id and years are already documented in detail, including the 1996–2025 year bounds and the note that valid files may lack observations. The description's statement that years selects 'API data-file start years' largely restates the schema, adding only marginal emphasis on empty-file behavior, so the baseline of 3 is appropriate.

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

Purpose5/5

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

The description names a specific resource and scope — institution-level earnings for federally aided undergraduate entrants who are working and not enrolled, regardless of completion — and enumerates exactly what is reported (6/8/10-year medians, 6/10-year percentiles, non-male/male 6-year medians). It also explicitly routes graduate-level earnings to scorecard_get_programs, so an agent can separate it from that sibling without inspecting schemas.

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

Usage Guidelines4/5

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

It gives a clear routing rule ('For graduate program earnings use scorecard_get_programs') and explains how the optional years array changes behavior, including the caveat that some files lack observations. It stops short of stating broader exclusions, such as when to prefer scorecard_value_analysis or compare tools, but the primary alternative is named.

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.