Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@CampusIntel MCP Find recent open-access papers on AI safety at MIT and list the researchers"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
CampusIntel is a Model Context Protocol server that gives AI assistants structured access to university research, researchers, academic programs, and institutional data. It combines the OpenAlex scholarly knowledge graph with the U.S. Department of Education's College Scorecard while preserving source links and limitations in every result.
The project is designed for research discovery and university investigation—not admissions predictions or one-number rankings.
An MCP server is a small piece of infrastructure that lets an AI host—such as Claude Desktop, VS Code, or the MCP Inspector—call reliable tools instead of guessing. Think of it as a secure adapter between an AI assistant and outside data sources.
CampusIntel is not a college-advice chatbot and it does not use an LLM to invent university
facts. It exposes clearly named functions such as search_research and
list_academic_programs. The AI host decides when to call them; CampusIntel validates the
request, obtains live data from the appropriate source, and returns structured, source-linked
results the host can explain to the user.
Related MCP server: OpenAlex Author Disambiguation MCP Server
sequenceDiagram
participant User
participant Host as AI host
participant CI as CampusIntel
participant Data as Data provider
User->>Host: "Find AI-safety research at a university"
Host->>CI: Call a typed MCP tool
CI->>CI: Validate inputs and check cache
CI->>Data: Request live, scoped data
Data-->>CI: Structured response
CI-->>Host: Normalized result with source URL
Host-->>User: Grounded answer with limitationsFor example, an AI host first calls search_universities to resolve a name to an OpenAlex
institution ID. It then passes that ID to search_research or find_topic_researchers. This
two-step pattern avoids ambiguous name matching and keeps research results tied to a specific
institution.
Tool | Purpose | Data source |
| Resolve university names to stable OpenAlex IDs | OpenAlex |
| Research footprint plus optional U.S. federal metrics | Both |
| Find papers by topic, university, year, and open-access status | OpenAlex |
| Find researchers by name and affiliation | OpenAlex |
| Discover researchers through relevant university papers | OpenAlex |
| Find U.S. colleges, costs, outcomes, and Scorecard IDs | College Scorecard |
| Filter fields of study and credential levels | College Scorecard |
| Produce a source-aware comparison for two to five schools | Both |
| Verify local provider configuration without exposing secrets | Local |
CampusIntel also exposes a campusintel://methodology resource and a reusable
research_university_fit prompt.
flowchart TD
Host["AI host or MCP Inspector"] --> Server["CampusIntel MCP server"]
Server --> Service["Validation and orchestration"]
Service --> OA["OpenAlex client"]
Service --> CS["College Scorecard client"]
OA --> Research["Institutions, works, authors"]
CS --> Federal["Programs, costs, outcomes"]The provider clients include typed normalization, bounded retries, timeouts, and an in-memory TTL cache. Cross-source matching is intentionally isolated in the service layer, so raw provider data and inferred relationships are never confused.
Source | CampusIntel uses it for | Important context |
Global universities, scholarly papers, authors, affiliations, topics, citations, and open-access links | It is an open scholarly index. Coverage and citation counts vary by field and publication age. | |
U.S. programs, enrollment, cost, admissions, completion, and earnings fields | It is published by the U.S. Department of Education. Its |
CampusIntel does not scrape faculty pages, use private student data, or claim it can predict an applicant's admissions outcome. It preserves the provider URL with each returned record so a user can check the primary data before relying on it.
Install uv, then clone and sync the project:
git clone https://github.com/acestein13/campusintel-mcp.git
cd campusintel-mcp
uv sync --all-extras --devNo virtual-environment activation is required when commands begin with uv run.
Copy .env.example to .env, then add your keys:
OPENALEX_API_KEY: recommended for normal use; create a free key in
OpenAlex settings.
COLLEGE_SCORECARD_API_KEY: required for U.S. institutional and academic-program tools;
request a free data.gov API key.
OpenAlex supports limited keyless demonstration requests. CampusIntel still works without a College Scorecard key, but the U.S. college and program tools will return a clear configuration error and profiles will omit Scorecard enrichment.
Never put a real key in README.md, source code, a committed .env file, a screenshot, or an
MCP configuration file you plan to share. This repository includes .env.example with blank
placeholders only, and .gitignore excludes .env.
Set OPENALEX_API_KEY and COLLEGE_SCORECARD_API_KEY as local environment variables, or place
their values only in your uncommitted .env file, then run uv run campusintel-mcp.
health_check reports only whether a provider is configured; it never returns secret values.
macOS/Linux:
set -a && source .env && set +a
uv run mcp dev src/campusintel_mcp/server.pyWindows PowerShell:
uv run mcp dev src/campusintel_mcp/server.pyBefore running the Windows command, define OPENALEX_API_KEY and
COLLEGE_SCORECARD_API_KEY in your local PowerShell session or in an uncommitted .env file.
The Inspector opens in a browser. Start with search_universities, retain the returned OpenAlex
ID, and pass it into the research tools.
The repository includes ready-to-edit examples for Claude Desktop and VS Code. Replace the absolute path and keep real keys outside files you commit or share.
A generic stdio entry is:
{
"command": "uv",
"args": ["--directory", "/ABSOLUTE/PATH/TO/campusintel-mcp", "run", "campusintel-mcp"]
}Local stdio is the default. To run the same server over Streamable HTTP:
CAMPUSINTEL_TRANSPORT=streamable-http uv run campusintel-mcpThe endpoint is http://127.0.0.1:8000/mcp. Host and port can be changed with
CAMPUSINTEL_HOST and CAMPUSINTEL_PORT.
docker build -t campusintel-mcp .
docker run --rm -p 8000:8000 \
-e OPENALEX_API_KEY \
-e COLLEGE_SCORECARD_API_KEY \
campusintel-mcpTo investigate AI safety research at a university, an MCP client can:
Call search_universities(query="Carnegie Mellon University", country_code="US").
Pass the returned ID into
search_research(topic="AI safety", institution_id="I...", from_year=2022).
Call find_topic_researchers with the same topic and institution ID.
Resolve the federal school ID with search_us_colleges, then call
list_academic_programs(query="computer science", credential_level=3).
Preserve the returned source URLs and methodology notes in the final answer.
“Compare recent robotics research at Georgia Tech and Carnegie Mellon. Link the source papers.”
“Find researchers working on AI safety at this university, then show the papers that made each person relevant.”
“For this U.S. school, list bachelor’s-level computer science programs and clearly separate program data from research metrics.”
The host should call the tools, not assume that a university name is enough to identify a single institution. CampusIntel's returned IDs make later calls precise and reproducible.
Input validation: empty queries, invalid years, duplicate comparison IDs, and invalid credential levels are rejected with an actionable tool error.
Reliable requests: provider calls use timeouts, bounded retries for transient failures, and a short-lived in-memory cache to reduce repeated requests.
Transparent missing data: unavailable fields remain null; CampusIntel does not fill them
with estimates or zeros.
Source-aware enrichment: U.S. federal metrics are added only when an OpenAlex institution can be reasonably name-matched to a Scorecard record, and the result is labeled accordingly.
No hidden rankings: citation counts, h-index values, and outcomes are descriptive context, never an overall university score or admissions prediction.
OpenAlex metrics reflect an indexed scholarly corpus; citation volume varies heavily by field, publication age, and coverage.
College Scorecard latest fields can come from different reporting cohorts.
Topic-researcher results are ranked within a relevance sample. They are not exhaustive faculty directories or judgments of researcher quality.
A missing value remains null; CampusIntel does not estimate it.
Name-based OpenAlex-to-Scorecard enrichment is labeled and should be verified before a consequential decision.
See the in-server campusintel://methodology resource for the same guidance in MCP clients.
uv run ruff format .
uv run ruff check .
uv run mypy src
uv run pytest --covThe test suite uses mocked HTTP transports plus the MCP SDK's in-memory client. CI runs formatting, linting, strict type checking, and tests on Python 3.11 and 3.12.
Released under the MIT License.
Compare two to five universities with source-aware research and U.S. federal metrics.
Args: institution_ids: Two to five OpenAlex institution IDs.
| Name | Required | Description | Default |
|---|---|---|---|
| institution_ids | Yes |
| Name | Required | Description |
|---|---|---|
| profiles | Yes | |
| methodology | Yes | |
| generated_from_live_data | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It mentions 'source-aware research' and 'U.S. federal metrics' but does not explain what these entail, how data is aggregated, whether it requires network calls, rate limits, or any side effects. The phrase 'source-aware' is vague and does not disclose potential deviations or limitations. The description does not contradict any structured data (no annotations exist), but it fails to provide meaningful behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and front-loaded, stating the core purpose and the input requirement in two sentences. No filler or redundant content. It is appropriately sized for a tool with a single parameter, though it sacrifices some detail for brevity. Structure is clean with an 'Args' section that mirrors the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of comparing multiple universities, the description is incomplete. While an output schema exists (not shown), the description does not explain what aspects of universities are compared (e.g., rankings, funding, research output) or what 'source-aware research' and 'federal metrics' mean. It also lacks error-handling or null-return guidance. The description is too terse to fully prepare an agent for invoking the tool correctly in diverse contexts.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only defines institution_ids as an array of strings with 0% description coverage. The description compensates by specifying that IDs are OpenAlex institution IDs and the expected count (two to five). This adds meaning beyond the type definition and clarifies the format and cardinality, which is valuable for correct invocation. It doesn't cover all nuances (e.g., exact ID format), but it provides the key semantic information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Compare') and the resource ('universities'), with a specific range of two to five. It also hints at the scope ('source-aware research and U.S. federal metrics'), which differentiates it from siblings like search_universities (search) and get_university_profile (single profile). It doesn't explicitly name a sibling, but the verb and range make the purpose distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by the action 'compare' and the range of IDs, but it does not explicitly state when to use this tool versus alternatives like get_university_profile or search_universities. No conditions, exclusions, or alternative recommendations are provided, so an agent must infer the correct context. The description is adequate but not explicit about when-not-to-use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Identify researchers connected to a topic at one university using matching works.
Results are ranked by matching paper count, then citations within the returned sample. This is a discovery aid, not an exhaustive faculty directory or quality ranking.
Args: topic: Research topic or keywords. institution_id: OpenAlex institution ID. limit: Number of researchers from 1 to 25.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| topic | Yes | ||
| institution_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses the ranking method (by matching paper count, then citations within the returned sample) and the limitation of being a discovery aid, not exhaustive. However, it does not mention the return format or any potential edge cases (e.g., empty results), though an output schema exists. It provides meaningful behavioral context but not complete coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured. The first sentence states the core purpose, followed by ranking and limitation notes, and then a clean Args list. It is front-loaded with the essential information and contains no fluff or repetition, maximizing readability for an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists, the description need not explain return values. It covers the tool's purpose, ranking behavior, limitations, and parameter semantics. While it doesn't mention prerequisites or error scenarios, these are not critical for a straightforward search tool with an output schema. Overall, it provides sufficient context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The 'Args' section adds semantic value beyond the bare schema properties. It clarifies that 'topic' can be keywords, 'institution_id' is specifically an OpenAlex ID, and 'limit' is a number from 1 to 25 (a range not present in the schema). This significantly helps an agent understand parameter usage, making it more than a repetition of schema names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Identify'), a resource ('researchers'), a context ('connected to a topic at one university'), and a method ('using matching works'). This clearly distinguishes it from siblings like search_researchers (general researcher search) and search_universities (institution search), leaving no ambiguity about what it does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by clarifying it is scoped to a single institution and is a 'discovery aid, not an exhaustive faculty directory or quality ranking.' However, it doesn't explicitly state when to prefer this tool over alternatives like search_researchers or when not to use it. The context is clear but exclusions are left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get an institution profile with research metrics and optional U.S. federal data.
Args: institution_id: OpenAlex institution ID, such as I136199984.
| Name | Required | Description | Default |
|---|---|---|---|
| institution_id | Yes |
| Name | Required | Description |
|---|---|---|
| scorecard | No | |
| data_notes | No | |
| institution | Yes | |
| research_impact_h_index | No | |
| two_year_mean_citedness | No | |
| research_impact_i10_index | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden, yet it discloses very little: no return format, no error behavior for invalid/missing IDs, and no explicit read-only signal. The phrase 'optional U.S. federal data' is ambiguous, since the sole input parameter cannot toggle anything — it is unclear what makes the federal data optional.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The definition is compact and front-loaded, with the one-sentence purpose first followed by a docstring-style arg note. Nothing is wasted, though the 'Args:' formatting is slightly redundant with the schema listing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one parameter, output schema present), so return values need not be spelled out. However, the missing when-to-use guidance and the ambiguous 'optional U.S. federal data' clause leave an agent without a fully reliable calling context, especially given the large sibling set.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, forcing the description to compensate. It does so well by explaining that institution_id is an OpenAlex institution ID and providing a concrete example format ('I136199984'). This adds meaning the schema lacks; only the absence of accepted-format variants or range details prevents a 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get') and resource ('institution profile with research metrics and optional U.S. federal data'). The resource description is detailed enough that the tool reads as a direct by-ID lookup, distinct from the search/compare siblings even without an explicit differentiation line.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. There is no mention that this is for a known OpenAlex ID while search_universities is for name-based discovery, no exclusions, and no stated prerequisites. An agent has no signal for choosing this over the search/compare siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report server and provider configuration without making external requests.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral disclosure burden. It explicitly guarantees no external requests, which is a key behavioral trait. It does not describe other behaviors like error handling or output format, but the existence of an output schema mitigates the need for format explanation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no redundancy. It front-loads the core purpose ('Report server and provider configuration') and appends the key constraint. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters, an output schema exists, and the description clearly states what it does and its non-external-request behavior, nothing essential is missing. An agent can confidently invoke it without further clarification.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema coverage is complete (100%) by default. The description adds no parameter semantics because none exist, which is appropriate. The baseline of 4 is justified given there is nothing to document.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Report') and a specific resource ('server and provider configuration'), and adds a distinguishing constraint ('without making external requests'). This clearly differentiates it from sibling search tools, which are all about academic data retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear context for use: it reports configuration without external requests, implying it is appropriate when a lightweight, side-effect-free status check is needed. While it doesn't explicitly name alternatives or exclusions, the sibling set is uniformly search-oriented, making the context obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List College Scorecard fields of study for one U.S. institution.
Args: school_id: College Scorecard school ID returned by search_us_colleges. query: Optional case-insensitive title filter, such as computer science. credential_level: Optional federal credential code from 1 through 8. limit: Number of programs from 1 to 100.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | No | ||
| school_id | Yes | ||
| credential_level | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says 'List' and provides parameter descriptions; it does not mention that the operation is read-only, whether results are paginated, or any error conditions. This is a significant gap for an unannotated tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single-line purpose followed by a compact, well-organized Args block. Every sentence provides useful information without redundancy, and the key purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists, the description need not explain return values. It covers all input semantics and the primary use case. It could mention whether results are sorted or limited, but the limit parameter and default are in the schema. Overall it is sufficient for an agent to call correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description includes an Args block that explains each parameter's meaning and constraints, such as query being a case-insensitive filter and credential_level being a code from 1 to 8. It also tells the source of school_id. Since the schema provides no parameter descriptions (0% coverage), this fully compensates and goes beyond the schema's type definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'College Scorecard fields of study for one U.S. institution.' It distinguishes itself from siblings like search_us_colleges (which searches for institutions) by emphasizing it operates on a single, known institution. The scope is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates that school_id is returned by search_us_colleges, implying a workflow of first finding a school then listing its programs. It does not explicitly mention alternatives or exclusions, but the context makes it clear when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search scholarly works by topic, optionally scoped to a university and date range.
Args: topic: Keywords or a research question. institution_id: Optional OpenAlex institution ID. from_year: Optional first publication year. to_year: Optional last publication year. open_access_only: Return only works OpenAlex marks as open access. limit: Number of works from 1 to 50.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| topic | Yes | ||
| to_year | No | ||
| from_year | No | ||
| institution_id | No | ||
| open_access_only | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the behavioral disclosure burden. It reveals the tool queries scholarly works via OpenAlex and offers open-access filtering, which implies read-only behavior. However, it doesn't explicitly state that it's non-destructive, mention rate limits, pagination, or what happens with no results. The description adds some context about the data source but stops short of full transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence followed by a compact, alphabetically listed parameter breakdown. No fluff or redundancy; every line contributes value. The purpose is front-loaded, and the args are straightforward.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the return format need not be explained. The description covers all parameters with semantics and the overall task. It lacks guidance on when to use this tool versus alternatives and doesn't mention any prerequisites or expected result counts, but for a simple search tool, the essential calling info is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully explain the parameters. It does this comprehensively: topic is defined as keywords or research question, institution_id as OpenAlex institution ID, from_year/to_year as publication year bounds, open_access_only as OpenAlex open-access filter, and limit with a range of 1 to 50. This is detailed, non-obvious, and goes well beyond the bare schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Search', the resource 'scholarly works', and optional scoping to a university and date range. It is specific enough to distinguish from siblings like search_researchers or search_universities, though it doesn't explicitly name them. The purpose is clear and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when not to use it or point to sibling tools like search_researchers or find_topic_researchers for different purposes. There is no explicit comparison or exclusion, leaving the agent to infer usage context on its own.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find researchers by name, optionally scoped to a last-known university affiliation.
Args: name: Researcher name or partial name. institution_id: Optional OpenAlex institution ID. limit: Number of researchers from 1 to 25.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| limit | No | ||
| institution_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the core read-only action and the parameter limit range (1–25), but does not mention output structure, rate limits, or any side effects. For a simple search tool this is minimally acceptable, but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: a one-sentence summary followed by a structured Args block. The core purpose is front-loaded, and every sentence adds value without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one required param), and the description covers all parameters plus the affiliation scoping nuance. Since an output schema exists, return values are not required in the description. It lacks minor details like search case-sensitivity, but these are likely implicit or covered by the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero descriptions for parameters (0% coverage), and the description compensates fully with explicit Args explanations: 'Researcher name or partial name', 'Optional OpenAlex institution ID', and 'Number of researchers from 1 to 25'. This adds meaning well beyond the schema titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'find researchers by name' with optional affiliation scoping. The verb 'find' and resource 'researchers' are specific, and the mention of 'by name' naturally distinguishes it from siblings like find_topic_researchers. No ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by name but does not explicitly contrast with alternatives such as find_topic_researchers or search_research. No when-not-to-use guidance is provided; usage context is inferred rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find universities worldwide and return stable OpenAlex IDs for later research calls.
Args: query: Full or partial university name. country_code: Optional two-letter ISO country code, such as US or GB. limit: Number of results from 1 to 25.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| country_code | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The verbs 'find' and 'return' imply a safe, read-only operation, and it adds useful context about stable OpenAlex IDs, indicating results are durable references for later use. However, with no annotations, it doesn't explicitly state read-only, rate limits, or failure behavior, though the search nature makes side effects unlikely.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One opening sentence clearly conveys the tool's purpose, followed by a compact Args block that covers all three parameters without redundancy. It is front-loaded and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple three-parameter search tool, the description provides complete invocation semantics and the output purpose. The presence of an output schema reduces the need to describe return structure. Minor omissions like pagination or sorting are not essential for a search capped at 25 results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description carries full responsibility for parameters. It explains query as a full or partial university name, country_code as a two-letter ISO code, and limit as a range from 1 to 25 – all meaningful additions beyond the bare schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Find'), resource ('universities worldwide'), and the output ('stable OpenAlex IDs'). The qualifier 'worldwide' distinguishes it from the sibling search_us_colleges, making the tool's scope clear without needing to open either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to choose this tool over siblings. It mentions 'for later research calls' as a downstream purpose, but it doesn't name alternatives like search_us_colleges for US-only queries or get_university_profile for detailed profiles, nor does it provide any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find U.S. colleges and return federal College Scorecard metrics and IDs.
Args: query: Full or partial institution name. state: Optional two-letter U.S. state abbreviation. limit: Number of results from 1 to 25.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| state | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It mentions the return type (metrics and IDs) but fails to disclose any behavioral traits such as result ordering, pagination, error handling, or any side effects. It does not state whether it's read-only or if there are limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the tool's purpose, followed by a clear list of arguments. No unnecessary text, each sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the parameters and basic output, but lacks usage context (e.g., when to prefer this over search_universities) and behavioral details like result limits or error handling. With an output schema present, return structure is likely covered, but the overall completeness is average.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has zero description coverage, and the description compensates by explaining each parameter: query as full or partial institution name, state as optional two-letter abbreviation, and limit with a range of 1-25. This adds meaning beyond the schema's property titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool finds U.S. colleges and returns federal College Scorecard metrics and IDs. It specifies the resource (U.S. colleges) and the data source (College Scorecard), distinguishing it from likely sibling tools that might search universities more broadly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like search_universities. It does not mention any exclusions or criteria for selecting this tool over similar search functions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0compare_universitiesfind_topic_researchersget_university_profilehealth_checklist_academic_programssearch_researchsearch_researcherssearch_universitiessearch_us_collegesScored across 9 tools
Most tools have clearly distinct purposes, but search_universities and search_us_colleges both find institutions, potentially causing confusion. However, the descriptions clearly differentiate them by scope (worldwide vs. US-specific) and ID type (OpenAlex vs. College Scorecard).
Tool names consistently use snake_case and mostly follow a verb_noun pattern (e.g., search_universities, get_university_profile, compare_universities). The outlier is health_check, which is a compound noun rather than a verb-first phrase, but it is still clear and fits the overall style.
With 9 tools, the server is well-scoped for university research and comparison. Each tool serves a distinct purpose without excessive specialization or unnecessary bloat, covering search, profiles, research, researchers, programs, and comparisons.
The surface covers core workflows for discovering universities, researching outputs, and comparing metrics. It lacks a dedicated tool to fetch a specific researcher's full profile or a specific work by ID, but these are minor gaps that agents can work around via search_researchers and search_research.
Academic literature search, retrieval, and private library management on top of OpenAlex.
Access the OpenAlex academic research catalog — 270M+ publications.
Search arXiv/Semantic Scholar/OpenAlex + medical evidence (PubMed/Europe PMC) + LaTeX/PDF tools.
OpenAlex MCP — wraps the OpenAlex API (scholarly works, free, no auth)
