APIbase

NIH Grant Publications

nihreporter.publications.by_project

Read-onlyIdempotent

Fetch PubMed IDs of publications tied to a specific NIH core project number, returning direct PubMed URLs and pagination so you can chain into abstract lookup.

Instructions

Retrieve PubMed IDs (PMIDs) of publications linked to a specific NIH core project number (e.g. "R01CA123456"). Returns up to 100 PMIDs per call with direct PubMed URLs. Use the core_project_num field from nihreporter.projects.search results. Chain with education.pubmed_search to fetch full titles and abstracts.

Input Schema

Name	Required	Description
`limit`	No	Number of publication PMIDs to return (1–100, default 50)
`offset`	No	Pagination offset — number of results to skip (default 0)
`core_project_num`	Yes	NIH core project number (e.g. "R01CA123456", "U54GM115371"). Returned as core_project_num in projects.search results.

Output Schema

Name	Required	Description	Default
`error`	No	Present only when the call failed. Includes error code, message, request_id, and any provider-specific extras.
`result`	No	Tool response payload. Shape varies per tool — consult the tool description and inputSchema. May be an object, array, string, or number depending on the upstream provider response.

Schema Changelog

Changes observed during successful MCP inspections.

Addedv2.2.0Oct 29, 2026

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover read-only, idempotent, open-world, and non-destructive behavior. The description adds useful behavioral detail: returns up to 100 PMIDs per call with direct PubMed URLs, which is beyond what annotations provide. Pagination via offset is implied but covered by schema, so this is well-handled.

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

Conciseness5/5

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

Three sentences with no wasted words. Each sentence serves a purpose: what the tool does, output characteristics, and how to obtain input and proceed next. The action and resource are front-loaded.

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

Completeness5/5

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

Given the output schema exists and annotations cover safety, the description is complete. It covers input source, expected output, limit, and a suggested downstream tool. An agent has everything needed to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema descriptions cover 100% of parameters, so baseline is 3. The description adds meaning by giving an example of core_project_num, noting it comes from projects.search, and clarifying the limit behavior ('up to 100 PMIDs'). This extra context helps the agent use parameters correctly.

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

Purpose5/5

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

Description states a specific verb ('Retrieve') and resource ('PubMed IDs of publications linked to a specific NIH core project number'). It clearly identifies the output (PMIDs with PubMed URLs) and differentiates from sibling tools like nihreporter.projects.search by focusing on publications.

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

Usage Guidelines4/5

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

Provides clear workflow guidance: 'Use the core_project_num field from nihreporter.projects.search results' and suggests chaining with education.pubmed_search. However, it does not explicitly mention when not to use this tool or name an alternative for the same purpose.

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

Deploy Server