OpenAlex MCP Server

search_institutions

Search academic institutions in the OpenAlex database using queries, filters, and sorting to find universities, research centers, and educational organizations.

Instructions

Search institutions

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "search_institutions"
  }
}

Input Schema

Name	Required	Description
`search`	No	Full-text search query
`filter`	No	Key:value OpenAlex filters. Supports entity attributes (e.g., 'ror', 'country_code', 'type'), IDs, and convenience filters (e.g., 'display_name.search'). Example: 'country_code:US,type:education'
`sort`	No	Sort field with optional :desc
`page`	No	Page number
`per_page`	No	Results per page (max 200)
`cursor`	No	Cursor for deep pagination
`group_by`	No	Group results by field
`select`	No	Fields to return
`sample`	No	Random sample size
`seed`	No	Random seed
`mailto`	No	Email for rate limits
`api_key`	No	Premium API key

Implementation Reference

src/tools/searchInstitutions.ts:3-10 (handler)
The handler function implementing the core logic of the 'search_institutions' tool. It makes an OpenAlex API request to the /institutions endpoint and returns the JSON response as text content.
```
export async function searchInstitutions(args: any) {
    return {
        content: [{
                type: "text",
                text: JSON.stringify(await makeOpenAlexRequest("/institutions", args), null, 2)
            }]
    };
}
```

src/index.ts:120-140 (schema)

The input schema and metadata for the 'search_institutions' tool, defined in the listTools handler.

{
    name: "search_institutions",
    description: "Search institutions",
    inputSchema: {
        type: "object",
        properties: {
            search: { type: "string", description: "Full-text search query" },
            filter: { type: "string", description: "Key:value OpenAlex filters. Supports entity attributes (e.g., 'ror', 'country_code', 'type'), IDs, and convenience filters (e.g., 'display_name.search'). Example: 'country_code:US,type:education'" },
            sort: { type: "string", description: "Sort field with optional :desc" },
            page: { type: "number", description: "Page number" },
            per_page: { type: "number", description: "Results per page (max 200)" },
            cursor: { type: "string", description: "Cursor for deep pagination" },
            group_by: { type: "string", description: "Group results by field" },
            select: { type: "string", description: "Fields to return" },
            sample: { type: "number", description: "Random sample size" },
            seed: { type: "number", description: "Random seed" },
            mailto: { type: "string", description: "Email for rate limits" },
            api_key: { type: "string", description: "Premium API key" }
        }
    }
},

src/index.ts:287-288 (registration)
Registration of the 'search_institutions' tool in the callTool request handler's switch statement, dispatching to the handler function.
```
case "search_institutions":
    return await searchInstitutions(args);
```
src/index.ts:25-25 (registration)
Import statement registering the searchInstitutions handler function for use in the MCP server.
```
import { searchInstitutions } from "./tools/searchInstitutions.js";
```

Schema Changelog

Changes observed during successful MCP inspections.

First observedDec 29, 2025

TDQS

D1.7/5.0

Behavior1/5

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 but offers none. It doesn't mention that this is a read-only operation, doesn't describe rate limits (though mailto and api_key parameters suggest they exist), doesn't explain pagination behavior beyond what's in the schema, and provides no information about response format, error conditions, or performance characteristics.

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

Conciseness2/5

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

While technically concise with just two words, this represents under-specification rather than effective brevity. The description fails to provide any of the necessary context that would help an AI agent understand when and how to use this tool. Every word should earn its place, but here the words don't provide meaningful value beyond the tool name itself.

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

Completeness1/5

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

For a complex tool with 12 parameters, no annotations, and no output schema, the description is completely inadequate. It doesn't explain what institutions are in this context, how results are returned, what the search capabilities are, or how this differs from other search tools. The agent would have to rely entirely on the parameter schema without any higher-level guidance about the tool's purpose and behavior.

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?

The schema description coverage is 100%, so all 12 parameters are documented in the schema itself. The description adds zero additional information about parameter usage, relationships, or semantics beyond what's already in the structured schema. This meets the baseline of 3 when the schema does all the parameter documentation work.

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

Purpose2/5

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

The description 'Search institutions' is a tautology that merely restates the tool name without adding any meaningful clarification. It doesn't specify what 'search' entails (full-text, filtered, paginated) or what 'institutions' refers to in this context. While the name itself suggests searching educational or research institutions, the description fails to elaborate on scope or purpose beyond the obvious.

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

Usage Guidelines1/5

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

The description provides absolutely no guidance on when to use this tool versus the many sibling tools listed (search_authors, search_works, search_funders, etc.). There's no indication of what distinguishes institution searching from other entity searches, nor any context about when this tool would be appropriate versus alternatives like get_entity or autocomplete.

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

Deploy Server