Provides access to PubMed/PubMed Central abstracts and full-text content, including PMC BioC fallback and resolution of PMID/PMCID identifiers for readable article retrieval.
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., "@Inciteful MCP Find influential papers in the citation graph around PMID 26017442."
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.
A TypeScript MCP server that combines OpenAlex paper search and metadata with Inciteful citation graphs. Runs locally over stdio using the official MCP TypeScript SDK v2. Requires Node.js 22 or newer.
npm install
npm run buildAdd this entry to your MCP client's configuration, replacing the absolute path:
{
"mcpServers": {
"inciteful": {
"command": "node",
"args": ["/absolute/path/to/inciteful-mcp/dist/index.js"],
"env": {
"OPENALEX_API_KEY": "your-optional-key",
"OPENALEX_EMAIL": "you@example.com"
}
}
}
}Omit the env entries you do not use. OpenAlex currently permits basic requests without a key; a key increases the available budget. See OpenAlex authentication. API access and quotas remain subject to upstream policies.
Environment variables:
Variable | Default | Purpose |
| unset | OpenAlex API key |
| unset | OpenAlex |
|
| Inciteful server |
|
| Per-request timeout, maximum 300000 |
.env is not loaded automatically. To use it, copy .env.example to .env, edit it, then run node --env-file=.env dist/index.js (or include --env-file=/absolute/path/.env before the script in your client's arguments). The server uses stdout exclusively for MCP messages.
Related MCP server: Semantic Scholar MCP Server
Tool | Purpose | Main inputs |
| OpenAlex topic/title search with cursor pagination |
|
| Full OpenAlex record or compact Inciteful record |
|
| Inciteful similarity with optional OpenAlex enrichment |
|
| Citation paths and directed edges between two papers |
|
| Rank a seed's graph by similarity, influence, or recency |
|
| Build a graph from 1–500 seeds and query literature-review sections |
|
| Readable OpenAlex abstract, with PubMed/PMC fallback |
|
| Potential PDF/article URLs with access and version metadata |
|
| Readable PMC or OpenAlex archive text, returned in chunks |
|
Limits default to 10 and cannot exceed 50. Search exposes OpenAlex's meta.next_cursor; pass it back as cursor for the next page. get_paper with OpenAlex returns the upstream record, including the inverted abstract index and reference IDs when available.
Example requests to an assistant using this server:
“Search for papers on deep learning in drug discovery, published since 2020.”
“Find 10 papers similar to DOI 10.1038/nature14539 and include OpenAlex metadata.”
“Connect PMID 26017442 to PMID 25462637.”
“Find influential papers in the citation graph around PMID 26017442.”
OpenAlex work IDs (W2919115771 or their URLs) are preserved as canonical graph identifiers. DOI and PMID aliases are accepted by the OpenAlex graph namespace and are batch-resolved to W IDs for literature reviews when OpenAlex metadata is available. Numeric OpenAlex IDs are never treated as legacy Inciteful numeric IDs. Similar-paper enrichment batches exact DOI matches in one OpenAlex request; unmatched records have openalex: null. An enrichment failure preserves the graph results and adds a warning. Records from each provider remain separate to preserve provenance.
Call literature_review with the complete seed list:
{
"ids": ["pmid:26017442", "pmid:25462637"],
"sections": ["similar_papers", "important_papers", "review_papers", "important_recent_papers"],
"limit": 10,
"year_from": 2020
}Those four sections are the default when sections is omitted. To expand the review, take the returned seed_ids, append interesting paper_id values from the results, and call the tool again. Every call specifies the complete seed set; the MCP server does not store a review session. The MCP accepts up to 500 input seeds (a local bound, not a claim about the upstream maximum). DOI, PMID, and OpenAlex aliases resolve to canonical Inciteful IDs before deduplication. An unresolved seed fails the call rather than silently changing the graph.
“Adding papers” means choosing the seed set for a graph, not executing SQL INSERT or creating new scholarly records. For multiple seeds, the live request is:
POST /openalex/query?ids%5B%5D=W2919115771&ids%5B%5D=W123456789&prune=10000
Content-Type: application/x-www-form-urlencoded
SELECT paper_id, distance FROM papers WHERE distance = 2The current graph namespace is /openalex and the parameter name is ids[], not the id[] shown in the OpenAPI spec. This was verified from Inciteful's academic frontend and successful live requests. A single canonical seed uses /openalex/query/{id}?prune=10000. Similarity, paper metadata, and connector calls use the same namespace.
Graph | Distance 0 | Distance 1 | Distance 2 |
Single paper | Seed | Direct citation neighbors | Neighbors of neighbors |
Multiple papers | Virtual paper | Selected seeds | Neighbors of the selected seeds |
These are undirected citation distances, as described in Inciteful's graph documentation. The virtual paper is omitted from results. All ranking sections exclude seeds; multi-paper similarity and review candidates specifically require distance 2.
Available sections, adapted from the supplied single- and multi-paper dashboard queries:
Section | Ranking or behavior |
| Seed nodes plus top similar candidate nodes; no edges |
| Adamic–Adar plus co-citation, then PageRank; requires a positive similarity component |
| PageRank, then Adamic–Adar |
| Outgoing citation counts, retaining the supplied repeated journal/year/count exclusion heuristic |
| Recent graph papers by the top 100 authors ranked by summed partial PageRank |
| PageRank among papers newer than current year minus three |
| Summed partial PageRank per author |
| Author ranking with earliest filtered graph publication newer than current year minus ten |
| Summed PageRank after deduplicating paper/institution affiliations |
| Summed PageRank per journal |
| Summed similarity per journal, then summed PageRank |
year_from and year_to are inclusive. title_contains is a literal substring (SQL quotes and wildcard characters are escaped). Filters apply to ranking candidates; the graph-node section always retains seeds. limit applies per section, with up to 500 extra seed nodes for similar_paper_graph.
The templates use COALESCE on both similarity components so co-citation-only matches are not lost. Authors are grouped by stable ID and name, avoiding name collisions. Recent top-author queries use the verified authors.partial_page_rank field in both graph modes. Journal similarity uses an aggregated PageRank tie-breaker instead of an arbitrary ungrouped row. “Review papers” are candidates, not confirmed review article types; “upcoming” reflects only the filtered graph, not an author's full career. The graph-node section includes all seeds explicitly, extending the supplied multi-paper node query for consistent iteration.
Seed metadata and aliases are resolved in batches of up to 50, reduced further for long identifiers. Every input is checked against returned IDs/DOIs; unresolved aliases are sent directly to the graph namespace, which can resolve DOI/PMID aliases itself. All canonical W IDs are then submitted together for each graph query. Thus 500 W-ID seeds normally need ten graph metadata requests plus one query per section; 500 DOI/PMID seeds may add up to ten optional OpenAlex alias-batch requests. Only concise seed metadata is returned. Results are Inciteful records; use get_paper with a result DOI for OpenAlex metadata. A failed section is reported under its error field with partial: true; successful sections remain available. If every section fails, the tool returns an MCP error.
The agent can read content directly through this MCP or retrieve publisher/repository copies using the URLs it returns:
get_abstract({"id":"10.1371/journal.pone.0000217"}) reconstructs readable text from OpenAlex's abstract index. If unavailable, a known PMID enables a PubMed BioC fallback. A PMCID can retrieve the abstract from PMC BioC directly.
get_full_text_links({"id":"10.1371/journal.pone.0000217"}) returns candidate URLs from best_oa_location, locations, primary_location, open_access.oa_url, and the OpenAlex content archive. Each link includes format, source, open-access flag, license, version, and whether an OpenAlex key is needed. Best-OA links come first; duplicates are removed. See OpenAlex locations.
get_full_text({"id":"PMC1790863","max_chars":15000}) fetches extracted article text. source defaults to auto: PMC BioC first, then OpenAlex Grobid XML if advertised and an API key is configured. Choose pmc or openalex to restrict the source.
The abstract/full-text tools accept a DOI, OpenAlex ID, PMID, Inciteful ID, PMCID (PMC1790863 or pmcid:PMC1790863), or a canonical PMC article URL. DOI/OpenAlex lookups need a PMID to use the PMC route. get_full_text_links uses OpenAlex-compatible IDs or an Inciteful ID resolvable to DOI/PMID.
Responses include the source URL and extracted text. Continue with the same id and source, setting offset to next_offset, until it is null. max_chars defaults to 15000 and is capped at 50000; offsets count JavaScript UTF-16 code units. The content_sha256 identifies the complete extracted text, so the agent can detect changes between pages. The process caches up to eight articles for 15 minutes to avoid downloading each chunk separately; cache contents are not written to disk. Each download is capped at 12 MiB.
PMC's BioC service supplies machine-readable article passages. OpenAlex's archive supplies PDFs and Grobid TEI XML; its downloads require OPENALEX_API_KEY and currently cost $0.01 per file. The MCP uses XML for text extraction. Ordinary publisher/repository URLs do not require an OpenAlex API key, though the destination may impose its own access requirements.
status: "not_retrieved" means none of the attempted sources supplied readable text; it does not establish that full text is unavailable everywhere. The response includes attempt details and candidate links when available. The agent can use its own browser/PDF tools on these URLs. The MCP does not currently scrape arbitrary publisher pages, extract PDFs, perform OCR, or authenticate with institutions. Extracted text may lose figure, equation, or table layout. Abstract-only BioC responses are not labeled as full text.
Claude Research Gateway is a separate Python MCP server using Playwright for institutional login and HTML/PDF extraction. It could run alongside this server: use Inciteful/OpenAlex for discovery, then hand a DOI or candidate URL to its fetch_paper tool. We have not installed it or copied its implementation.
The current choice is to implement abstract retrieval, content links, and structured full-text retrieval directly here. Institutional login remains an optional next layer requiring the institution/proxy details and an interactive login. Before adopting the gateway's session handling, address its HTTP-200-only session validation and loss of cookie Secure/expiry attributes during HTTP-client injection. Its authentication detection also relies on page/domain heuristics, so actual article access needs verification after login.
Implemented against Inciteful's API documentation, its OpenAPI specification, graph schema documentation, and OpenAlex's API reference. Live checks on September 16, 2026 found:
The Inciteful spec advertises a different server URL; this project uses the requested graph.incitefulmed.com host.
Paper/path IDs can be strings such as pmid:26017442, despite numeric IDs in the schema.
Similar-paper count uses the query parameter n, despite the spec marking it as a path parameter.
condensed=true can still return citation arrays. The server removes them from compact paper results.
The current frontend graph routes are under /openalex: paper metadata, similarity, connector, and raw SQL query. The MCP now sends the same prune=10000 query parameter and raw SQL form body.
POST /openalex/query/{OpenAlexWorkID} and multi-seed POST /openalex/query?ids[]=... can return more rows than the SQL LIMIT; the MCP applies its requested limit locally.
An earlier MCP 404/500 for W7154975096 was caused by using the legacy root routes and converting the W ID to a DOI before graph lookup. The corrected adapter preserves W7154975096; live MCP calls for lookup, similarity, and discovery now pass.
/bib returned an empty body for the tested paper and remains unexposed. The frontend uses a separate /export/bib route, which has not been implemented here.
OpenAlex singleton DOI lookup requires the DOI URL form; a bare DOI returned 404. The server normalizes it automatically.
Citation paths are capped locally; truncated indicates omitted paths and num_paths retains the upstream total. Only papers and edges among the returned paths are included. Graph coverage can differ from OpenAlex; missing records are reported as errors rather than silently substituted. Results reflect upstream data and graph scores, which do not establish research quality or clinical validity.
Requests have timeouts, schema checks, bounded result counts, and sanitized errors. There are no automatic retries, crawling, persistent caching, or bulk harvesting. Each similar-paper request makes one graph call plus at most one OpenAlex enrichment call; resolving an OpenAlex seed adds a lookup. Avoid high-volume graph use; Inciteful asks users planning thousands of papers or hundreds of graphs to contact them first.
npm run dev
npm run check
npm test
npm run buildTests use mocked API responses, local SQLite query execution, and a real stdio MCP client/server exchange; they do not call live services. SQLite tests require Node.js 22.13 or newer. Live API checks are separate from the repeatable test suite.
After building, npm run smoke tests the original five tools through MCP against the live APIs, including DOI enrichment. npm run smoke:review tests all 11 review sections in both single- and multi-seed modes (22 graph queries plus seed lookups). Both require network access. All 22 review queries passed live verification on September 16, 2026.
To check a larger seed set explicitly, place an array of known paper IDs in a JSON file and run npm run smoke:review -- /absolute/path/seeds.json. This runs similarity and influence queries for that seed set. A live 200-seed review passed both queries on September 16, 2026; the 500-seed batching and request shape are covered by mocked tests. Large reviews may need a longer MCP client call timeout; REQUEST_TIMEOUT_MS controls each individual upstream request.
npm run smoke:content checks OpenAlex abstract retrieval, candidate URLs, and paginated PMC full text through MCP. These passed live verification on September 16, 2026. OpenAlex authenticated archive downloads are covered by mocked tests and have not been verified with a live key. Content downloads reject redirects; sources requiring redirects remain available as candidate links for agent retrieval.
Find citation paths between two papers using Inciteful. Returns paths, edge directions, and the papers on the returned paths.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | DOI, OpenAlex W ID/URL, PMID, or an Inciteful-supported identifier. | |
| from | Yes | DOI, OpenAlex W ID/URL, PMID, or an Inciteful-supported identifier. | |
| max_paths | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the operation read-only, idempotent, and non-destructive. The description adds useful behavioral detail by specifying the returned elements (paths, edge directions, papers) and the external Inciteful backing, going beyond what annotations signal without contradicting them.
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 two sentences with the core action front-loaded and the return values in the second sentence. There is no repetition or filler.
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 read-only tool with no output schema, the description adequately covers the input relationship and high-level return format. It does not explain max_paths behavior or path/edge-detail semantics, but the schema and annotations cover the remaining essentials, so the gaps are minor.
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 adds no meaning beyond the input schema: from/to are already documented as DOI/OpenAlex/PMID/identifiers, and max_paths is neither described in the schema nor the tool description. With 67% schema coverage, the description leaves the max_paths parameter semantically unaddressed.
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 action ('find citation paths'), the resource ('between two papers'), the source ('using Inciteful'), and the return contents. This clearly distinguishes it from sibling tools like similar_papers or get_paper.
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 use case is implied—when you have two papers and want citation paths—but there is no explicit statement of when to choose this over similar_papers or discover_papers, nor any exclusions or prerequisites. An agent must infer the fitting scenario from the purpose alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rank papers in an Inciteful graph around one seed paper by similarity, PageRank influence, or publication year. Excludes the seed. Similarity is a graph metric, not a quality assessment.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | DOI, OpenAlex W ID/URL, PMID, or an Inciteful-supported identifier. | |
| limit | No | ||
| ranking | No | similarity |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds value by stating that the seed is excluded and that similarity is a graph metric, not a quality assessment, which provides behavioral nuance beyond the annotations.
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 two sentences with no redundant phrasing. Key information (ranking function, criteria, seed exclusion) is front-loaded, and the caveat about similarity is concise. 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 tool with three parameters, no output schema, and rich annotations, the description covers the core purpose, ranking options, and an important caveat. It omits details about the limit parameter and return format, but the absence of an output schema reduces the need to describe returns. Overall, it is adequate 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?
Schema description coverage is only 33% (only the id parameter is described). The description explains the ranking enum (similarity, influence, recent) but does not mention the limit parameter or its constraints. It partially compensates for low schema coverage but leaves the limit parameter undocumented in both schema and description.
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 it ranks papers in an Inciteful graph around a seed paper, specifying ranking criteria (similarity, PageRank influence, publication year) and explicitly notes the seed is excluded. It also clarifies that similarity is a graph metric, not a quality assessment, which distinguishes its purpose from generic search or retrieval tools.
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 a use case (ranking papers around a seed) but does not explicitly state when to choose this over sibling tools like similar_papers or search_papers. No exclusion criteria or alternative routing is provided, leaving the agent to infer context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a readable abstract from OpenAlex, falling back to PubMed/PMC BioC. Returns source attribution and candidate full-text links.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | DOI, OpenAlex work ID, PMID, or Inciteful ID. Abstract/full-text tools also accept PMC12345 or a PMC article URL. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: the fallback order from OpenAlex to PubMed/PMC BioC, and the return content of source attribution and candidate full-text links.
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?
Two sentences carry the essential information: what is retrieved, from where, fallback behavior, and what is returned. There is no filler or repetition of schema/annotation content.
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 single-parameter, read-only tool with a well-documented schema and no output schema, the description is complete. It explains the purpose, fallback sources, and return value shape, giving an agent enough context to invoke it 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?
Schema coverage is 100%, and the id parameter description fully documents the accepted identifier formats including DOI, OpenAlex work ID, PMID, Inciteful ID, PMC12345, and PMC article URLs. The description adds no additional parameter semantics, so the baseline of 3 is appropriate.
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 ('Retrieve'), a specific resource ('a readable abstract'), and names the primary and fallback sources (OpenAlex, PubMed/PMC BioC). It also distinguishes this tool from the full-text siblings by explicitly returning source attribution and candidate full-text links rather than the full text itself.
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 purpose is clear: use this when you need a readable abstract with source attribution and candidate full-text links. It provides clear context for selection, though it does not explicitly mention when to prefer a sibling tool such as get_full_text or get_paper.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch readable article text from PMC BioC, or OpenAlex structured XML when an API key is configured (archive download charges may apply). Returns chunks with next_offset and content hash. If retrieval fails, returns candidate URLs for the agent to fetch with web/PDF tools. Does not scrape arbitrary publisher sites.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | DOI, OpenAlex work ID, PMID, or Inciteful ID. Abstract/full-text tools also accept PMC12345 or a PMC article URL. | |
| offset | No | ||
| source | No | auto | |
| max_chars | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as read-only, idempotent, and non-destructive, but the description adds substantial behavioral detail beyond that: it returns chunks with next_offset and content hash, may incur archive download charges, falls back to candidate URLs on failure, and refuses to scrape arbitrary publisher sites. This gives the agent a realistic model of tool behavior.
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?
Four sentences, each earning its place: primary behavior, return format, failure fallback, and an explicit exclusion. The most important information is front-loaded, and there is no redundant restating of the tool name or schema fields.
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 multiple sources, conditional API key, failure behavior, and absence of an output schema, the description is fairly complete. It covers the key behaviors needed to use the tool correctly)Skip: it does not fully document all parameter semantics, especially max_chars and offset, and it does not specify the shape of the returned chunks or candidate URLs. Still, this is a minor gap given annotations already cover the safety profile.
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 only 25%, so the description needs to compensate for the three undocumented parameters. It partially does—'from PMC BioC, or OpenAlex structured XML' maps to the source enum, and 'Returns chunks with next_offset' hints at pagination semantics. But offset, max_chars, and the precise way to configure the OpenAlex API key are not explained in the description.
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 operation ('Fetch readable article text'), identifies two distinct sources (PMC BioC and OpenAlex structured XML), and sets boundaries by saying what it does not do ('Does not scrape arbitrary publisher sites'). It is distinct from siblings like get_abstract and get_full_text_links, which are about abstracts and links respectively.
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 gives practical context: it mentions the API-key condition for OpenAlex, charges, and the fallback to web/PDF tools when retrieval fails. However, it never names sibling tools such as get_full_text_links or get_abstract, nor does it explicitly state when to choose this tool over those alternatives. Usage guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return potential full-text PDF and article URLs from OpenAlex, ordered with its best open-access copy first. Includes license/version/access metadata and archive URLs. Use your web tools to fetch publisher or repository links; availability is not guaranteed.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | DOI, OpenAlex W ID/URL, PMID, or an Inciteful-supported identifier. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds useful behavioral context: ordering by best open-access copy, inclusion of license/version/access metadata and archive URLs, and the non-guarantee of availability. No contradiction with annotations.
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?
Three sentences, each conveying essential information: what is returned, how results are ordered, and how the agent should use the output. No filler or redundancy.
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 return content (URLs, metadata, archive links), ordering, and caveats. Since there is no output schema, this is sufficient for a simple one-parameter tool. Minor omissions like pagination or result limits are not critical given the tool's scope.
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 100%, and the `id` parameter is already well-described in the schema with accepted identifier formats. The description does not add further parameter-level meaning, so the baseline of 3 applies.
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 and resource: 'Return potential full-text PDF and article URLs from OpenAlex.' It clearly differentiates from the sibling get_full_text by emphasizing URLs/links rather than content, and adds ordering and metadata details.
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?
It gives actionable guidance: 'Use your web tools to fetch publisher or repository links' and warns availability is not guaranteed. It clearly implies this tool returns links for fetching rather than content, though it does not explicitly name get_full_text as the alternative for full-text content.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a paper from OpenAlex (full metadata, DOI/OpenAlex ID/PMID) or Inciteful (compact graph metadata and citation counts).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | DOI, OpenAlex W ID/URL, PMID, or an Inciteful-supported identifier. | |
| source | No | openalex |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds the key behavioral distinction that the response format depends on the chosen source – full metadata via OpenAlex versus compact graph metadata with citation counts via Inciteful. It does not cover error cases or rate limits, but given the annotations, this is a minor gap.
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?
A single sentence with clear structure, no filler, and the core information 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?
For a simple two-parameter retrieval tool with read-only annotations and no output schema, the description covers the primary decision (source selection) and the identifier types. It lacks explicit return-value details but the high-level statement of 'full metadata' or 'compact graph metadata' gives the agent enough context to call it 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 schema documents the id parameter's accepted formats, and the description reinforces it by naming DOI/OpenAlex ID/PMID, while also giving semantic meaning to the source parameter by describing what metadata each source returns. However, it does not elaborate on what qualifies as an 'Inciteful-supported identifier', leaving some ambiguity for that parameter.
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 ('Retrieve'), a resource ('paper'), and the two data sources with their metadata types, which clearly distinguishes it from sibling tools like get_abstract and get_full_text that target different content.
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 the tool is for retrieving a paper by identifier and contrasts OpenAlex (full metadata) with Inciteful (compact graph metadata), but it does not explicitly state when to choose this over alternatives like search_papers or get_abstract, nor when not to use it. The usage context is inferred rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Build and query a literature-review graph from 1–500 seed papers. Returns selected paper, author, institution, and journal rankings based on Inciteful dashboard queries. To add papers, call again with the returned seed_ids plus selected result paper_id values. Batches OpenAlex/Inciteful identifier resolution and deduplicates canonical seeds. Multi-seed similarity and review candidates use distance 2; seeds are excluded from rankings. Review-paper and upcoming-author labels are graph heuristics. No persistent review state is stored.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | Yes | ||
| limit | No | ||
| year_to | No | ||
| sections | No | ||
| year_from | No | ||
| title_contains | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context beyond annotations: identifier resolution batching, deduplication, distance-2 similarity, seed exclusion from rankings, and the heuristic nature of labels. It also states 'No persistent review state is stored,' which reinforces the idempotent/read-only behavior. This goes beyond what annotations alone communicate.
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 moderately long but each sentence conveys distinct information: the core function, the iterative usage pattern, the batching/dedup behavior, the distance parameter, label heuristics, and the lack of persistent state. It is front-loaded with the main purpose and doesn't contain filler. It could be slightly more concise, but the density is justified given the tool's complexity.
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 essential operational aspects: the seed range, the ranking types, the iterative expansion, the distance-2 rule, seed exclusion, label heuristics, and statelessness. It does not detail the exact structure of the returned rankings or the output schema (which is absent), but for a complex tool it provides sufficient context for an agent to understand what it does and how to use it iteratively. Minor gaps remain in return format, but the description is relatively complete for the given complexity.
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 input schema itself provides descriptions for parameters, including the 'ids' field with supported identifiers and the 'sections' enum. The tool description does not add deeper parameter semantics beyond mentioning 'seed papers' as a general concept. Since the schema carries the parameter documentation (despite the 0% coverage metric referring to the description), a baseline of 3 is appropriate – the schema does the heavy lifting, and the description doesn't conflict or add much.
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's purpose: it builds and queries a literature-review graph from 1-500 seed papers and returns rankings of papers, authors, institutions, and journals. The verb 'build and query' is specific, and the resource is well-defined. It distinguishes itself from siblings like 'similar_papers' or 'discover_papers' by focusing on a graph built from seeds and returning aggregated rankings.
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 explicit usage guidance: 'To add papers, call again with the returned seed_ids plus selected result paper_id values.' It also notes that multi-seed similarity uses distance 2 and seeds are excluded from rankings. However, it does not explicitly state when this tool is preferred over siblings or when not to use it, leaving some room for inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search OpenAlex for papers by topic or title. Returns metadata and next_cursor for pagination. Use selected IDs with get_paper or similar_papers.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| cursor | No | * | |
| filter | No | Optional OpenAlex filter, e.g. publication_year:2020-2026,is_oa:true |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the description adds value by disclosing the pagination behavior via next_cursor and indicating that the tool returns metadata. This is useful context beyond the annotations, though it does not address limits, ordering, or API-specific quirks.
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 two concise sentences with no filler. The core purpose is front-loaded, and the pagination and follow-up usage details are packed efficiently.
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 read-only search tool, the description is minimally adequate, and annotations cover safety. However, with no output schema, it does not explain the returned metadata fields, how pagination actually works, or how to combine filters with the query. It also does not differentiate from sibling discovery tools.
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 only 25%, with only the filter parameter having a description in the schema. The description adds partial meaning by mentioning next_cursor for pagination, which hints at the cursor parameter, but it does not compensate for the lack of documentation on limit, query semantics, or cursor usage syntax.
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 and resource ('Search OpenAlex for papers by topic or title'), which clearly identifies the tool's core purpose. It also distinguishes itself from downstream tools like get_paper and similar_papers by mentioning their role in using selected IDs, but it does not explicitly contrast with sibling search/discovery tools such as discover_papers.
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 when to use the tool: when searching by topic or title, and it provides a follow-up workflow ('Use selected IDs with get_paper or similar_papers'). However, it does not say when to choose this tool over alternatives like discover_papers or literature_review, and there is no explicit when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find related literature using Inciteful citation graph similarity, optionally enriched with OpenAlex metadata via exact DOI matches. OpenAlex IDs are resolved to DOI/PMID first. Graph coverage may be narrower than OpenAlex.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | DOI, OpenAlex W ID/URL, PMID, or an Inciteful-supported identifier. | |
| limit | No | ||
| enrich | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety. The description adds valuable behavioral context: the Inciteful citation-graph mechanism, optional OpenAlex enrichment via exact DOI matches, ID resolution to DOI/PMID, and the caveat that graph coverage may be narrower than OpenAlex. This goes beyond the annotations and helps set expectations.
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?
Three focused sentences (~40 words) with no filler. The main purpose is front-loaded, followed by enrichment detail and a coverage caveat. Every sentence earns its place; it's both concise and well-ordered.
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 read-only tool with three parameters, annotations, and no output schema, the description covers the core behavior, how input IDs are handled, the optional enrichment, and a key limitation. It doesn't describe the response shape or the exact semantics of 'limit', but given the simplicity and the annotations, the agent has enough to invoke it correctly. A 4 reflects this nearly complete picture.
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 only 33% (only 'id' has a description). The tool description partially compensates: it clarifies 'enrich' via 'optionally enriched with OpenAlex metadata' and explains ID handling for 'id' ('OpenAlex IDs are resolved to DOI/PMID first'). However, the 'limit' parameter is left entirely undocumented, and no default/range context is given. The description adds some value but doesn't fully cover the gap, so a 3 is appropriate.
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 it 'Find[s] related literature using Inciteful citation graph similarity,' which is a specific verb, resource, and method. It implies a similarity-focused search distinct from search_papers or get_paper, though it does not explicitly name a sibling it is not. Slightly more differentiation would earn a 5.
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 the use case (finding related literature) but offers no explicit guidance on when to prefer this over siblings like discover_papers or literature_review, nor when not to use it. It mentions the enrichment option but doesn't state conditions for choosing alternatives. This is adequate but leaves the agent to infer.
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.
v0.1.0connect_papersdiscover_papersget_abstractget_full_textget_full_text_linksget_paperliterature_reviewsearch_paperssimilar_papersScored across 9 tools
Each tool targets a distinct research workflow step: search, retrieval, similarity, citation paths, discovery, review, abstracts, and full-text. Similar purposes exist between similar_papers and discover_papers, but their methodological differences are clearly described, avoiding significant confusion.
Tool names mostly follow a verb_noun pattern (search_papers, get_paper, connect_papers, get_abstract, get_full_text). A few names deviate slightly, such as similar_papers and literature_review, but the convention is consistent enough to be predictable and readable.
With 9 tools, the set is well-scoped for a scholarly research assistant covering search, discovery, analysis, and retrieval. Each tool has a clear role without unnecessary proliferation or redundancy.
The tools cover the full research lifecycle: searching, retrieving metadata, exploring citation relationships, ranking and discovering papers, building literature reviews, and obtaining abstracts and full text. No major gaps are evident for the stated academic research domain.
Academic literature search, retrieval, and private library management on top of OpenAlex.
Search 340M+ academic papers — citation graphs, semantic similarity, and AI literature reviews.
Academic paper search, scientific literature, citation analysis, arXiv & semantic related-work.
Scholarly search: OpenAlex, Crossref, arXiv, OpenCitations and PubMed in one endpoint.
