college-scorecard-mcp-server

Search Schools

scorecard_search_schools

Read-only

Search and filter U.S. colleges and universities by name, location, type, size, and acceptance rate. Returns core identity and cost metrics. Use scorecard_get_school for profiles or scorecard_search_programs for programs. Geographic distance requires a U.S. ZIP; ZIP alone uses the provider default radius. State accepts comma-separated two-letter codes (e.g. WA,CA). Ownership: 1=public, 2=private nonprofit, 3=for-profit. Degree level: 0=Not classified, 1=certificate, 2=associate, 3=bachelor, 4=Entirely graduate-degree granting.

Input Schema

Name	Required	Description
`zip`	No	Five-digit U.S. ZIP or ZIP+4. Alone uses the provider default radius; blank is unset.
`page`	No	Zero-indexed page number for pagination.
`sort`	No	Upstream sort expression on an indexed field, e.g. "latest.cost.avg_net_price.overall:asc" or ":desc" for reverse order. Use scorecard_list_fields for sort support; omission keeps API ordering.
`query`	No	School name search — partial or full name; all words must appear.
`state`	No	Comma-separated two-letter state codes; case and whitespace normalized, blanks unset.
`cip_code`	No	Filter to schools offering this CIP 4-digit program code (e.g. "11.07"). Use scorecard_lookup_cip to find codes.
`distance`	No	Nonnegative radius: bare miles, mi, or km, including decimals. Requires meaningful zip.
`men_only`	No	True selects men-only institutions; false selects institutions explicitly marked not men-only. Omit to include unknown values.
`per_page`	No	Results per page (max 100).
`ownership`	No	Control type: 1=public, 2=private nonprofit, 3=private for-profit.
`size_range`	No	Undergraduate enrollment size range. Omit for no size filter.
`women_only`	No	True selects women-only institutions; false selects institutions explicitly marked not women-only. Omit to include unknown values.
`degree_level`	No	Predominant degree: 0=Not classified, 1=certificate, 2=associate, 3=bachelor, 4=Entirely graduate-degree granting.
`acceptance_rate_range`	No	Acceptance rate range as decimals (0–1). Omit for no filter.

Output Schema

Name	Required	Description
`cap`	No	The per_page limit that was applied.
`page`	No	Current page (zero-indexed).
`error`	No	Present when the call failed. Absent on success.
`query`	No	Normalized effective selectors and pagination defaults.
`shown`	No	Institutions returned on this page.
`total`	No	Total institutions matching the filters (before pagination).
`notice`	No	Recovery hint when results are empty — echoes applied filters and suggests how to broaden.
`schools`	No	Matching institutions.
`per_page`	No	Results per page used.
`truncated`	No	True when school pagination metadata indicates a later page exists.
`totalCount`	No	Total institutions matching the filters, before pagination.

Schema Changelog

Changes observed during successful MCP inspections.

Changed9 schema fields changedNov 3, 2026

changedInput schema / properties / degree_level / description

Previous value: -"Predominant degree: 0=non-degree/certificate, 1=certificate, 2=associate, 3=bachelor, 4=graduate."New value: +"Predominant degree: 0=Not classified, 1=certificate, 2=associate, 3=bachelor, 4=Entirely graduate-degree granting."

addedOutput schema / properties / schools / items / properties / attendance_basis

Added value: +{
+  "description": "Period of the effective attendance cost, selected independently of tuition.",
+  "enum": [
+    "academic_year",
+    "program_year"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / schools / items / properties / attendance_program_year

Added value: +{
+  "description": "Reported program-year cost of attendance.",
+  "type": "number"
+}

addedOutput schema / properties / schools / items / properties / cost_of_attendance

Added value: +{
+  "description": "Available academic-year attendance cost, otherwise program-year cost.",
+  "type": "number"
+}

addedOutput schema / properties / schools / items / properties / effective_tuition

Added value: +{
+  "description": "Available academic-year tuition, otherwise program-year tuition.",
+  "type": "number"
+}

addedOutput schema / properties / schools / items / 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 / schools / items / properties / ope6_id

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

addedOutput schema / properties / schools / items / properties / tuition_basis

Added value: +{
+  "description": "Period of the effective tuition.",
+  "enum": [
+    "academic_year",
+    "program_year"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / schools / items / properties / tuition_program_year

Added value: +{
+  "description": "Reported program-year tuition and fees.",
+  "type": "number"
+}

First observedOct 13, 2026

TDQS

A4.2/5.0

Behavior4/5

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds useful behavioral context beyond them: the result scope (core identity and cost metrics) and the silent default-radius behavior when only a ZIP is supplied. It does not discuss pagination limits or empty-result behavior, which keeps it from a 5.

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?

Front-loaded with purpose, then alternatives, then parameter notes, with no filler sentences. It loses a little by restating the ownership and degree-level code tables that the schema already carries verbatim.

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

Completeness5/5

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

For a 14-parameter search tool with nested range objects and an output schema, the description covers purpose, sibling routing, geographic and state syntax, and the coded filters. Return values can be left to the output schema, so nothing an agent needs in order to call it correctly is missing.

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 every parameter is already documented, and the numeric code mappings for ownership and degree_level are repeated almost verbatim from the schema. The ZIP/distance interaction is the one place it adds meaning beyond the schema, so this sits at the baseline for a fully-covered schema.

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?

States a specific verb and resource (search/filter U.S. colleges and universities) plus the filterable dimensions, and explicitly distinguishes itself from two siblings (scorecard_get_school for profiles, scorecard_search_programs for programs). An agent can route correctly without opening any schema.

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?

Names the alternative tools and what each is for, and adds a real usage constraint (geographic distance requires a U.S. ZIP; ZIP alone falls back to the provider default radius). It does not state the inverse case (when not to use this tool if e.g. you already have a school ID), so it stops just short of fully explicit exclusion guidance.

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.