org.opennih/opennih

Use this tool when the user asks what KINDS of awards NIH (or one Institute) makes — 'how much goes to R01s vs training grants', 'what share of NCI's portfolio is centers', 'break NIH down by mechanism'. Returns counts and recorded totals per mechanism class (research / career / training / center / contract / intramural / ...) from ranking_core.classify. Scope is whole-NIH or one Institute; per-institution portfolios are served by the institution-profile surface instead. Bounds: fiscal years 1985-2100 with fiscal_year_start <= fiscal_year_end; ic is a free-text filter with no length cap. Not paginated.

Use this tool to retrieve the full record for one NIH grant by its id. Returns {id, title, text, url, metadata} with url set to the public OpenNIH grant page so the client can cite it. This is the citation-record wrapper resolving the canonical row for an id. The record is PROJECT-level, not project-year: when a project number owns several project-year rows the LATEST fiscal year is returned (metadata.matching_rows reports how many rows exist). Bounds: id is REQUIRED and must be a full NIH project number matching ^[A-Z0-9-]{1,24}$ (e.g. 1R01CA123456-01A1); core project numbers and partial numbers do not match. An id that matches no row in the corpus raises an error — a missing grant can also mean it was added to RePORTER after the snapshot cutoff, so it is absent here rather than nonexistent.

Use this tool when the user asks about the RATE of change rather than the level — 'is this university's NIH funding growing', 'what's the CAGR since 2015', 'who grew fastest'. Returns year-over-year growth plus a window CAGR for one institution (entity_id, the canonical institution identifier) or all NIH. Both yoy_growth_pct and cagr_pct are PERCENTS (2.5905 means 2.5905%/yr, not 259%); the old fractional `cagr` key is gone. NULL awards are excluded, never padded to $0. meta echoes entity_id + organization so looped calls stay attributable. Bounds: fiscal years 1985-2100 with fiscal_year_start <= fiscal_year_end; entity_id is matched exactly with no length cap. Not paginated.

Use this tool to get yearly NIH funding totals and grant counts. Returns a time series for the whole NIH, one Institute/Center, one activity code, or one institution. Use it when the user asks 'how much NIH funding was awarded in FY2020', 'how has NIH's budget changed over time', or 'plot R01 dollars by year'. total_funding spans ALL NIH mechanisms (funding_scope="all_mechanisms") and is therefore 1.5-1.7x larger than research-only ranking totals for the same slice, so the two are not comparable. Rows flag the partial current fiscal year. Bounds: fiscal years 1985-2100 and fiscal_year_start <= fiscal_year_end; ic, activity_code and institution are free-text filters with no length cap (matched as parameterized SQL, never interpolated). Not paginated: the whole requested year range is returned.

Use this tool when the user asks about one named institution — 'what is Harvard's NIH funding history', 'which PIs does this university fund', 'what mechanisms does it win'. entity_id is the canonical institution identifier (from the institution ranking); grant-search results do NOT carry one. Read-only institution profile: funding history, mechanism mix, top PIs. fiscal_year_start/fiscal_year_end scope EVERY aggregate section — the mechanism-mix, funding-trend AND top-PIs sections all report only that fiscal-year window, and provenance.fiscal_year_window echoes the window actually applied; omit both arguments for all fiscal years. meta.found and profile.organization are deliberately window-independent (they answer existence/identity, so a real entity with no funding in the window stays found with its name). meta.found is always an explicit boolean: false (with profile=null) when the entity_id matches nothing in the corpus, true otherwise — branch on it instead of null-checking funding fields. The funding-trend rows' fiscal_year is int OR null: null means 'fiscal year not reported', never 0, and such a group belongs to no fiscal-year window, so it is absent from every scoped section. Bounds: entity_id 2-256 characters, fiscal years 1985-2100.

Use this tool when the user asks about one researcher — 'how much NIH funding does Dr. X have', 'list this PI's grants', 'who does she collaborate with'. profile_id is the NIH RePORTER PI identifier carried in grant-search results' pi_profile_id field and is not guessable. Read-only PI profile: grants, collaborators, publications, funding totals; the headline name/institution follow the PI's LATEST grant. A fiscal-year window with no grants returns the profile with total_grants=0, not an error. COUNT SEMANTICS (#762): profile.grant_count counts project-year rows (one per fiscal year a grant was funded), while profile.active_grants counts DISTINCT active awards — core project numbers — whose rows are active, so a continuing award counted across several fiscal years in grant_count counts ONCE in active_grants. fiscal_year_start/fiscal_year_end scope EVERY aggregate section — grants, profile totals AND collaborators all report only that window (issue #342; collaborators previously ignored it and returned the all-time list). COLLABORATOR COVERAGE: the collaborator sidecar covers only SOME fiscal years, so an empty collaborators list can mean 'unknown for these years' rather than 'none'. meta.collaborator_coverage.window_covered distinguishes the two: false = no data for any year in the window, and true with window_fully_covered=false means PARTIAL coverage, with the uncovered years listed in missing_fiscal_years_in_window. fiscal_years_with_collaborator_data lists the years that do have it. PI ROLE (#761): each grant carries pi_role — contact (this person is the row's contact PI) or co_investigator (matched via the corpus multi-PI list, so awards someone else leads still count toward totals); meta.multi_pi_ids_loaded=false means the corpus predates that list and only contact-PI rows can match, and meta.present_only_as_non_contact_pi=true means the id is never a contact PI anywhere (headline name/institution are then empty). SUBPROJECT ROWS (#761): award_amount NULL with subproject_component=true marks a component row of a multi-project award whose dollars are carried by another row of the same project and fiscal year — subproject_note names that amount; NULL WITHOUT the flag means not reported. Bounds: profile_id 1-20 digits (^[0-9]{1,20}$), fiscal years 1985-2100, limit 1-50 (default 20), offset 0-100000.

Use this tool when the user asks what ONE NIH Institute funds in a topic — 'what is NCI spending on immunotherapy', 'does NIMH fund psychedelics research', 'compare NIAID and NCI on vaccines' (call it once per Institute), or ic='ALL' for every IC at once. The response states which surface produced the numbers in match_strategy: 'rcdc' (official NIH RCDC categories, FY2008+) or 'text' (project_title match, used when the topic is not an RCDC category or the requested window is below the measured 50% RCDC-density minimum; provenance.rcdc_window_coverage reports the actual density). On the RCDC surface each grant is counted once even when several of its categories match. Bounds: ic and query are BOTH REQUIRED, 2-64 characters each; fiscal years 1985-2100 with fiscal_year_start <= fiscal_year_end. Not paginated.

Use this tool when the user asks how concentrated or unequal NIH funding is across institutions — 'is NIH money concentrated in a few universities', 'what share do the top 5 take', 'has inequality grown since 2000'. Returns gini, hhi, top5_share and the top-5 institutions over the competitive RPG-research scope (NULL awards excluded, never padded to $0). Bounds: fiscal years 1985-2100 with fiscal_year_start <= fiscal_year_end. Optional `ic` narrows the scope to one NIH institute when it is an IC abbreviation such as NCI or NIGMS. Any other string is matched as a NAME FRAGMENT and can span several institutes; `meta.ic_scope.kind` reports `fragment` and how many institutes matched. Omit `ic` for all-NIH. Not paginated.

Use this tool when the user asks what mix of award types ONE institution wins — 'is this university mostly R01s or centers', 'how much of its NIH money is training', 'compare two schools' portfolios'. entity_id is the canonical institution identifier (from the institution ranking). With entity_id it returns that institution's whole NIH-administered portfolio (all mechanism classes); without it, the system-wide RPG-research breakdown — the two scopes are NOT comparable. Counts are grouped by comparability_group and never summed across classes. Bounds: fiscal years 1985-2100 with fiscal_year_start <= fiscal_year_end; entity_id is matched exactly (padded and unpadded DUNS spellings both resolve) with no length cap. Not paginated.

Use this tool when the user asks which institutions get the most NIH money — 'top NIH-funded universities', 'where does NCI money go', 'rank research hospitals by R01 funding'. Each ranked row also yields its entity_id, the canonical institution identifier. Ranks institutions by competitive RPG-research NIH funding (R01 baseline), excluding intramural/contracts/centers/career/training, de-duplicated on core_project_num; NULL total_funding is not reported, never $0. total_funding here is RPG-research-only and is NOT comparable to the all-mechanism NIH totals served elsewhere. Bounds: limit 1-50 (default 20), offset 0-100000, fiscal years 1985-2100, ic 2-64 chars (NIH abbreviation or code, e.g. NCI or CA), sort_by one of composite | funding_scale | portfolio_breadth | new_grant_activity | avg_award_size.

Use this tool when a research or connector client needs citation-shaped NIH grant hits for a natural-language query. Returns {"results": [{id, title, text, url}]} where id is the NIH project_num and url is the public OpenNIH grant page. Each record is PROJECT-level, not project-year: ids are unique within a response, and the record always describes the project's CANONICAL row — its latest fiscal year, resolved WITHOUT the query filter, so it is exactly the canonical row for that id. One NIH project number can span many sub-awards with unrelated titles (center grants such as P41/P50/P01 are the common case), so the returned title and snippet may contain none of the query terms — the sibling row that matched the query text is not necessarily the canonical row, and the canonical row is the page the citation opens; a match alone does not establish that a returned grant is about the query. This is the citation-record wrapper: citation-shaped records only — it takes no filters (institution, IC, fiscal year, activity code) and returns no funding totals or provenance. Bounds: query is REQUIRED and matched over grant titles at 2-64 characters (a blank query returns no results instead of the whole corpus); limit 1-50 (default 20) distinct grants per page; offset 0-10000 skips matching project-year rows exactly, so stepping offset by limit walks the full result set page by page — results past the first page are reachable, not invisible. A page is the de-duplicated projection of that row window: one project number owning rows in two windows (multi-component awards emit one row per sub-project) can appear on more than one page, and ids are unique within each response.

Use this tool when the user asks to find NIH grants — by topic, principal investigator, institution, NIH Institute/Center, activity code, fiscal year, or project number ('what NIH grants exist on CRISPR', 'show me Stanford's R01s in 2022', 'look up 5R01CA036569-02'). This is the primary entry point: results carry pi_profile_id, the NIH RePORTER PI identifier. Read-only bounded search over the entity-resolved NIH ExPORTER/RePORTER corpus; results include mechanism_class, funding_basis and provenance, and a null award_amount means not reported, never zero. pi_name matches either name order ('Michael Platt' = 'PLATT, MICHAEL'; corpus form is LAST, FIRST). Bounds: query/text_search/institution/pi_name 2-64 chars, project_num ^[A-Z0-9-]{1,24}$, activity_code ^[A-Z0-9]{1,5}$, fiscal years 1985-2100, limit 1-50 (default 20), offset 0-100000 (offset>10000 is rate-limited to 12/min — partition by fiscal_year instead). meta.total_funding is the full matching-slice sum, not the returned page. Results are cached for ~1 hour. Counting: one result is one source application-year row, so (project_num, fiscal_year) is NOT unique - a multi-component award (P/U center) emits one row per sub-project, so the same project_num can appear several times in one fiscal year with different PIs and titles. These are distinct NIH application records, not duplicates. Each row carries appl_id, the NIH application id and authoritative row identity - two rows sharing (project_num, fiscal_year) with different appl_id are distinct sub-project applications, and appl_id is the key to de-duplicate on. meta.total counts rows, not grants; meta.unique_project_nums counts distinct project numbers, and meta.distinct_awards (row field core_project_num) counts distinct awards.

Use this tool when the user asks whether the OpenNIH corpus is loaded, which official sidecars are available, or how stale the data might be — and before reporting 'no such grant', since corpus_lag_note explains that a grant added to RePORTER after the snapshot cutoff is absent here, not nonexistent. Read-only status for the deployed NIH project corpus and official sidecars. Takes no parameters; no caller paths or external URLs are accepted.

Use this tool when the user asks how a research topic has trended over time — 'is CRISPR funding growing', 'how many p53 grants per year', 'when did NIH start funding long COVID'. Returns yearly project-row counts plus recorded award totals for a title keyword match; multi-word queries AND their words in any order. Bounds: query is REQUIRED, 2-64 characters; fiscal years 1985-2100 with fiscal_year_start <= fiscal_year_end. Not paginated.