search_works
Search scholarly works in the OpenAlex database using queries, filters, sorting, and pagination to find research papers and academic publications.
Instructions
Search scholarly works in OpenAlex
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| search | No | Full-text search query | |
| filter | No | Key:value OpenAlex filters. Supports entity attributes (e.g., 'publication_year', 'is_oa'), IDs, and convenience filters (e.g., 'title.search'). Example: 'is_oa:true,type:journal' | |
| sort | No | Sort field with optional :desc (e.g., 'cited_by_count:desc') | |
| page | No | Page number (max 10,000 results total) | |
| per_page | No | Results per page (max 200) | |
| cursor | No | Cursor for deep pagination (use '*' for first call) | |
| group_by | No | Group results by field for faceting | |
| select | No | Comma-separated list of fields to return | |
| sample | No | Random sample size | |
| seed | No | Random seed for reproducible sampling | |
| mailto | No | Email for rate limits | |
| api_key | No | Premium API key | |
| bearer_token | No | Bearer token for authentication | |
| view | No | The view of the data to return. 'summary' returns a concise version, 'full' returns the complete object. |
Implementation Reference
- src/tools/searchWorks.ts:4-41 (handler)The handler function that executes the search_works tool logic. It calls the OpenAlex API for /works endpoint, optionally summarizes results (limits authorships and concepts) based on 'view:summary' parameter, and returns formatted JSON response.export async function searchWorks(args: any) { const { view, ...searchArgs } = args; if (view === 'summary') { // Define the fields for the summary view searchArgs.select = 'id,doi,title,publication_year,type,cited_by_count,authorships,concepts,primary_location,open_access,best_oa_location'; const data = await makeOpenAlexRequest("/works", searchArgs); // Process the results to create the summary const summarizedResults = data.results.map((work: Work) => { // Limit authorships if (work.authorships && work.authorships.length > 5) { work.authorships = work.authorships.slice(0, 5); } // Limit concepts if (work.concepts && work.concepts.length > 3) { // Assuming concepts are sorted by score, which is typical. // If not, we might need to sort them first. work.concepts = work.concepts.slice(0, 3); } return work; }); return { content: [{ type: "text", text: JSON.stringify({ ...data, results: summarizedResults }, null, 2) }] }; } else { return { content: [{ type: "text", text: JSON.stringify(await makeOpenAlexRequest("/works", args), null, 2) }] }; } }
- src/index.ts:58-76 (schema)Input schema definition for the search_works tool, specifying parameters like search, filter, sort, pagination, and view options.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., 'publication_year', 'is_oa'), IDs, and convenience filters (e.g., 'title.search'). Example: 'is_oa:true,type:journal'" }, sort: { type: "string", description: "Sort field with optional :desc (e.g., 'cited_by_count:desc')" }, page: { type: "number", description: "Page number (max 10,000 results total)" }, per_page: { type: "number", description: "Results per page (max 200)" }, cursor: { type: "string", description: "Cursor for deep pagination (use '*' for first call)" }, group_by: { type: "string", description: "Group results by field for faceting" }, select: { type: "string", description: "Comma-separated list of fields to return" }, sample: { type: "number", description: "Random sample size" }, seed: { type: "number", description: "Random seed for reproducible sampling" }, mailto: { type: "string", description: "Email for rate limits" }, api_key: { type: "string", description: "Premium API key" }, bearer_token: { type: "string", description: "Bearer token for authentication" }, view: { type: "string", "enum": ["summary", "full"], description: "The view of the data to return. 'summary' returns a concise version, 'full' returns the complete object." } } }
- src/index.ts:55-77 (registration)Registration of the search_works tool in the ListTools response, including name, description, and schema.{ name: "search_works", description: "Search scholarly works in OpenAlex", 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., 'publication_year', 'is_oa'), IDs, and convenience filters (e.g., 'title.search'). Example: 'is_oa:true,type:journal'" }, sort: { type: "string", description: "Sort field with optional :desc (e.g., 'cited_by_count:desc')" }, page: { type: "number", description: "Page number (max 10,000 results total)" }, per_page: { type: "number", description: "Results per page (max 200)" }, cursor: { type: "string", description: "Cursor for deep pagination (use '*' for first call)" }, group_by: { type: "string", description: "Group results by field for faceting" }, select: { type: "string", description: "Comma-separated list of fields to return" }, sample: { type: "number", description: "Random sample size" }, seed: { type: "number", description: "Random seed for reproducible sampling" }, mailto: { type: "string", description: "Email for rate limits" }, api_key: { type: "string", description: "Premium API key" }, bearer_token: { type: "string", description: "Bearer token for authentication" }, view: { type: "string", "enum": ["summary", "full"], description: "The view of the data to return. 'summary' returns a concise version, 'full' returns the complete object." } } } },
- src/index.ts:281-282 (registration)Dispatch/registration in the CallToolRequest handler switch statement that invokes the searchWorks handler.case "search_works": return await searchWorks(args);
- src/index.ts:22-22 (helper)Import statement that resolves to the searchWorks handler implementation.import { searchWorks } from "./tools/searchWorks.js";