works_citing_paper
Retrieve papers that cite a specific academic work from the OpenAlex database, enabling researchers to track citation impact and discover related literature.
Instructions
Retrieves works that cite a given paper from the OpenAlex API.
Args: paper_id: An OpenAlex Work ID of target paper. e.g., "https://openalex.org/W123456789" sort_by: The sorting criteria ("cited_by_count", or "publication_date"). page: The page number of the results to retrieve (default: 1).
Returns: A JSON object containing a list of papers+ids citing the specific paper, or an error message if the retrieval fails.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| paper_id | Yes | ||
| sort_by | No | cited_by_count | |
| page | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| data | No | ||
| page | Yes | ||
| has_next | No | ||
| per_page | Yes | ||
| total_count | No |
Implementation Reference
- src/server.py:394-453 (handler)The main handler function for the 'works_citing_paper' tool. It is decorated with @mcp.tool for registration and implements the logic to fetch works citing a given paper from the OpenAlex API using the filter 'cites:{paper_id}', with pagination and sorting.
async def works_citing_paper( paper_id: str, sort_by: Literal["cited_by_count", "publication_date"] = "cited_by_count", page: int = 1, ) -> PageResult: """ Retrieves works that cite a given paper from the OpenAlex API. Args: paper_id: An OpenAlex Work ID of target paper. e.g., "https://openalex.org/W123456789" sort_by: The sorting criteria ("cited_by_count", or "publication_date"). page: The page number of the results to retrieve (default: 1). Returns: A JSON object containing a list of papers+ids citing the specific paper, or an error message if the retrieval fails. """ params = { "filter": f"cites:{paper_id}", "sort": f"{sort_by}:desc", "page": page, "per_page": 10, } # Fetches search results from the OpenAlex API async with RequestAPI("https://api.openalex.org", default_params={"mailto": OPENALEX_MAILTO}) as api: logger.info(f"Searching for works citing paper using: paper_id={paper_id}, sort_by={sort_by}, page={page}") try: result = await api.aget("/works", params=params) # Returns a message for when the search results are empty if result is None or len(result.get("results", []) or []) == 0: error_message = f"No cites found for paper_id={paper_id}." logger.info(error_message) raise ToolError(error_message) # Successfully returns the searched papers works = Work.from_list(result.get("results", []) or []) success_message = f"Found {len(works)} cites to paper_id={paper_id}." logger.info(success_message) total_count = (result.get("meta", {}) or {}).get("count") if total_count and total_count > params["per_page"] * params["page"]: has_next = True else: has_next = None return PageResult( data=Work.list_to_json(works), total_count=total_count, per_page=params["per_page"], page=params["page"], has_next=has_next ) except httpx.HTTPStatusError as e: error_message = f"Request failed with status: {e.response.status_code}" logger.error(error_message) raise ToolError(error_message) except httpx.RequestError as e: error_message = f"Network error: {str(e)}" logger.error(error_message) raise ToolError(error_message)