Search Works
crossref_search_worksSearches the Crossref works index (~188M records) by free text and/or structured filters. The generic query matches loosely across all fields; scope precisely with the field-specific parameters queryTitle, queryAuthor, and queryContainerTitle, or resolve a known citation to its DOI with queryBibliographic — all combine with each other and with query. Use the filter parameter for structured filtering (object with hyphen-separated Crossref keys). Sort options: relevance, score, is-referenced-by-count, published, deposited, indexed, created. Each work returns at most authorLimit authors (25 by default) with authorCount reporting the full deposited total, since a single page of large-collaboration papers can carry tens of thousands of author entries; crossref_get_work pages the whole author list for any DOI whose list was cut. Funding acknowledgements with their award numbers, license terms, and registered full-text links come back only when fields names funder, license, or link, in the entry shapes crossref_get_work uses; each work then carries at most 25 funders, with funderCount the full deposited total. Post-publication updates ride each work as Crossref records them: updatedBy names each correction, retraction, expression of concern, or new version issued against it, and updateTo the works it is itself a notice for — an absent updatedBy does not mean the work was never updated. Set facets to count the matching works per value of a field — per publication year, publisher, type, funder, affiliation, ORCID, and more — over the whole match set in the same call; rows: 0 returns the counts alone. Offset-based paging is capped at ~10K results; use cursor="*" to start cursor-based deep paging, then pass the nextCursor value from each response to continue. A walk with a query term and no sort runs by relevance, one with filters only in Crossref registration order. The walk ends on the page where nextCursor is absent — that page also carries a notice saying the list is exhausted. Cursor and offset cannot be combined.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "crossref_search_works"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| rows | No | Number of results to return per page (default 20): 0–500 per call when fields names abstract or author, or is omitted or empty, which selects every field but funder, license, and link; 0–200 when fields names funder, license, or link, whatever else it names; 0–1000 when fields names none of those five. A value above 500 under the first kind of selection returns 500 and says so in notice, and one above 200 under the second returns 200 the same way — on an offset page the notice also names the offset that continues after the records returned. 0 returns no works, only totalResults and any facets, and does not advance a cursor walk. | |
| sort | No | Sort field. Omitted, an offset page with a query term is ranked by relevance, and so is a cursor walk with one (sent as score). The publication-date sorts (published, published-print, published-online) work with offset paging only — Crossref refuses them alongside cursor; every other sort works with either. | |
| order | No | Sort direction (asc or desc). Applies only alongside sort; without one it has no effect. | |
| query | No | Free-text search query, e.g. "CRISPR gene editing" or "climate change adaptation" | |
| cursor | No | Cursor token for deep paging. Pass "*" to start cursor-based paging (required past ~10K results), then pass the nextCursor value from each response until a response omits it, which means the list is exhausted. A walk with a query term runs by relevance unless sort is set; a walk with filters only runs in Crossref registration order. Relevance scores shift slightly between identical requests, so a relevance walk can repeat or skip a record at a page boundary — sort:"created" walks every match without repeats. Cannot be combined with offset, or with a publication-date sort (published, published-print, published-online), which Crossref does not walk by cursor. | |
| facets | No | Value counts over the whole match set — the records totalResults counts, not just this page — keyed by facet name, each set to "*" or a number of values. Crossref returns the values with the highest counts, at most 1000 per facet; a facet whose values reach its limit may have more, and notice names it. Example: {"published":"*","publisher-name":10} counts works per publication year and for the 10 publishers with the most. Pair with rows: 0 for the counts alone. | |
| fields | No | Fields to return (reduces payload). Names are case-sensitive, and each fills one output field: DOI → doi, title → title, type → type, author → authors and authorCount, published / published-print / published-online → published, approved → approved, container-title → containerTitle and containerTitles, event → event, publisher → publisher, member → memberId, is-referenced-by-count → isReferencedByCount, score → score, abstract → abstract, volume → volume, issue → issue, page → page, article-number → articleNumber, ISSN → issn, updated-by → updatedBy, update-to → updateTo, funder → funders and funderCount, license → licenses, link → links. Omitted or empty, every name but funder, license, and link is selected; those three are returned only when named here. A work's funders are capped at the first 25, with funderCount the deposited total. A grant record carries no funders: its funder sits under its project, a field a works list cannot select. A selected field absent from a work means the record does not deposit it. DOI is always returned whether or not it is listed here, so every result stays resolvable by crossref_get_work, which also returns a work's whole funder list and the fields this list does not cover (references, relations, and the rest of the record). | |
| filter | No | Structured filter object using Crossref hyphen-separated keys. All values must be strings. Boolean flag keys (has-abstract, has-references, has-full-text) require string values "true" or "false". Dissertations, and most standards, deposit their date as an approval date rather than a publication date, which the pub-date filters (from-pub-date, until-pub-date) do not read — bound them by date with from-approved-date and until-approved-date. Example: {"type":"journal-article","has-abstract":"true","from-pub-date":"2023-01-01"} | |
| offset | No | Zero-based result offset for offset-based paging. Cannot be used with cursor. Capped at ~10K: offset + rows cannot pass it, so a page that would returns the rows that fit and says so in notice, and an offset at or past it is refused. Use cursor for deeper paging. A search with filters only and no sort has no fixed order: identical requests can order its records differently, so successive offsets can repeat or skip one — sort:"created" with order:"asc" holds the order. | |
| queryTitle | No | Match against work titles only, e.g. "Array programming with NumPy". | |
| authorLimit | No | Maximum number of authors to return per work (1–500 per call, default 25; a larger value, up to 100000, applies 500 and says so in notice). Ordinary records fit under the default; large-collaboration papers deposit thousands, and a page of them is large enough to exhaust a client context. Each work reports its full deposited total as authorCount — call crossref_get_work with that work doi to page the authors this cap left out. | |
| queryAuthor | No | Match against author names only, e.g. "Charles R. Harris". | |
| queryBibliographic | No | Whole-citation match to resolve a known reference to its DOI. Combine title, author, year, and container into one string, e.g. "Watson Crick molecular structure of nucleic acids Nature 1953". | |
| queryContainerTitle | No | Match against the container title (journal or book name) only, e.g. "Nature". |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cap | No | The per-work author cap applied to this page. Absent when no list was cut. | |
| error | No | Present when the call failed. Absent on success. | |
| works | No | Matching works. Empty when nothing matched the query, when an offset runs past the end of the results, or on the page that ends a cursor walk — the notice enrichment says which — and on every page requested with rows: 0. | |
| facets | No | One entry per facet requested, in the order requested. Counts cover every record totalResults counts, not just this page, so every page of a cursor walk carries the same ones. A work that deposits no value for the facet is in no count, and one that carries several (several affiliations, a retraction that is also an erratum) is in each. Absent when facets was not set or was empty. | |
| notice | No | Guidance on an empty page, naming which of its three causes applies: a query nothing matched, an offset past the end of a list that did match, or a cursor walk that has reached the end of the list. A rows: 0 page names only the first, and beside a cursor says that the page does not advance the walk. On a page carrying records, present when authorLimit cut at least one work's author list or the 25-funder cap one work's funder list, naming how many and the route to the rest; when a grant row lacks the title a selection of both type and title asked for, naming crossref_get_work as the route to it; or when every query term and filter value was supplied blank, so the page lists the whole index unfiltered. On any page, present when rows or authorLimit was above its per-call cap, naming the value requested and the cap applied — for rows under a fields selection naming funder, license, or link, also the caps a selection without them takes; under one naming abstract or author, also that one naming neither takes rows up to 1000; on an offset page with records remaining, also the offset that continues after the records returned. On an offset page where offset + rows would pass the ~10K offset ceiling, present naming the rows requested and the rows that fit and were applied, and, when records remain past the ceiling, cursor as the route to them. Present when a facets count was above 1000, naming the count requested and the 1000 applied, and when a facet returned as many values as its limit, naming the facet and the route to the values it may have left out. A page needing more than one caveat carries them all in this one string. | |
| returned | No | Number of records returned in this response | |
| truncated | No | True when at least one work on this page had its author list cut by authorLimit. Absent when every work on the page carries its full deposited author list. | |
| nextCursor | No | Cursor token to pass as cursor on the next call to continue a cursor walk. Present only on a page requested with cursor that returned works: absent once the walk reaches the end of the list, and on a rows: 0 page, which does not advance it. | |
| totalResults | No | Total matching records in Crossref |