Skip to main content
Glama

Search DataCite works

datacite_search_works
Read-onlyIdempotent

Search DataCite DOI metadata for datasets, software, samples, workflows, and other research outputs. Combine plain words (text) or OpenSearch query syntax (query) with filters for resource type, creator (ORCID iD or name), affiliation (ROR ID or name), affiliation country, funder (ROR ID, Crossref Funder ID, or name), subject, field of science, repository, provider, license, language, geographic place, publication-year range, and minimum citation count. Returns the total match count and compact rows — DOI, title, first creators, year, type, repository, licenses, and citation/view/download counts — plus optional top facet counts. The total counts DOIs, so a versioned work counts once per DOI — its concept DOI and each version DOI, as Zenodo registers them; set version_scope to series to count each version series once, or releases to count only the versions. Page numbers reach the first 10,000 ranked matches; pass cursor "*" to walk any result set in full, in registration order.

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": "datacite_search_works"
  }
}

Input Schema

NameRequiredDescriptionDefault
pageNoRanked page number, 1 when omitted. page × limit may not exceed 10,000; not with cursor.
sortNorelevance, newest, oldest, recently_updated, most_cited, most_viewed, or most_downloaded. Omitted: relevance when text or query is set, else newest. Not with cursor.
textNoPlain words and phrases, searched literally: query-syntax characters are escaped, so "Climate change: impacts" works. Angle brackets are removed; nonblank text with no remaining searchable clause is rejected. Blank text is unset. Terms are ANDed.
limitNoRequested rows per page, a positive integer (default 20); values above 1,000 apply 1,000 with a notice unless strict limits are configured.
placeNoA place name, matched anywhere inside deposited place names, so India also matches Indiana. Tried as typed, in lowercase, in uppercase, with every word capitalized, and with the first word capitalized: give a multi-word name its usual capitalization (Gulf of Mexico). For one exact, case-sensitive name, use query geoLocations.geoLocationPlace:"Svalbard" instead.
queryNoOpenSearch query-string syntax — field paths (titles.title:"…", creators.name:…, relatedIdentifiers.relationType:…), AND/OR/NOT, ranges, wildcards. Field paths: datacite_list_reference topic query_syntax. ANDed with text and the filters.
cursorNoCursor walk over the full result set in registration order: "*" to start, then the nextCursor of the previous page, unchanged, with the same query and filters. Not with page or sort.
funderNoA funder ROR ID, a Crossref Funder ID (10.13039/100000001, its doi.org URL, or the bare digits), or a funder name — every name token must appear in one funding reference.
creatorNoA creator ORCID iD (0000-0002-1825-0097, 16 digits, or an orcid.org URL; checksum verified) or a name — every name token must appear in one creator field.
subjectNoA subject phrase, matched case-insensitively against subject terms.
languageNoISO 639-1 language code of the work, any case (en, de).
licensesNoThe work's own license ids (any match), e.g. cc-by-4.0, cc0-1.0, cc0 1.0, mit. Trimmed and lowercased, then matched exactly, preserving internal spaces; reuse ids from the licenses facet or datacite_list_reference topic licenses.
affiliationNoA ROR ID (021nxhr62 or a ror.org URL) — matches creator and contributor affiliations — or an affiliation name phrase.
provider_idsNoProvider ids (any match), e.g. dryad — the providerId datacite_search_repositories returns. Any case.
published_toNoLatest publication year (inclusive). Alone, the range is open-ended.
min_citationsNoOnly works DataCite records at least this many citations for.
version_scopeNoWhich DOIs of a versioned work count. all (default): every DOI, so a Zenodo upload counts at least twice — its concept DOI and each version DOI. series: drops every record asserting IsVersionOf, so a version series counts once, through its concept DOI; a version whose concept DOI fails another filter (a later publication year, a changed creator or affiliation) or lies outside DataCite is not counted at all. releases: drops every record asserting HasVersion, so each version counts and concept DOIs drop out. Neither collapses Figshare's .vN DOIs, which point at their base DOI with IsIdenticalTo, so those pairs still count twice.
include_facetsNoAdd top facet counts (resource types, years, repositories, providers, affiliations, fields of science, licenses). Adds 2–8 s.
published_fromNoEarliest publication year (inclusive). Alone, the range is open-ended.
repository_idsNoRepository ids (any match), shaped provider.repository — e.g. dryad.dryad or cern.zenodo — as datacite_search_repositories returns them in repositoryId. Any case.
resource_typesNoresourceTypeGeneral values (any match): dataset, software, computational-notebook, workflow, model, physical-object, … PascalCase accepted. Full list: datacite_list_reference topic resource_types.
fields_of_scienceNoOECD Fields of Science ids or labels (any match), e.g. computer_and_information_sciences or "Earth and related environmental sciences". List: datacite_list_reference topic fields_of_science.
affiliation_countryNoCurrent or formerly assigned ISO 3166 alpha-2 country of a creator or contributor affiliation, plus XK; any case (DE, us). UK aliases to GB with a notice. Unassigned codes, alpha-3 codes and names are rejected.
include_child_fundersNoAlso match the funder's child organizations in ROR. Needs funder as a ROR ID, or a Crossref Funder ID that resolves to exactly one ROR ID; rejected with a funder name or no funder.

Output Schema

NameRequiredDescriptionDefault
errorNoPresent when the call failed. Absent on success.
worksNoMatching works on this page.
facetsNoTop facet counts — only with include_facets.
noticeNoGuidance when nothing matched, paging stops short of the total, or the page is past the end.
nextPageNoNext ranked page number, when more results lie within the 10,000 ceiling.
nextCursorNoPass as cursor, unchanged and with the same query and filters, to read the next page of a walk; absent on the last page.
totalCountNoTotal DOIs matching the query and filters; a versioned work counts once per DOI (see version_scope).
sortAppliedNoThe sort order applied; a cursor walk is always oldest (registration order).
appliedFiltersNoEvery applied filter as sent upstream; {} when none.
effectiveQueryNoThe composed query string sent upstream.
rankedCeilingReachedNoTrue when ranked paging stops before all matches have been delivered; restart with cursor "*".

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed8 schema fields changed
    • changedInput schema / properties / funder / description
      Previous value: -"A funder ROR ID, a Crossref Funder ID (10.13039/100000001, its doi.org URL, or the bare digits), or a funder name."New value: +"A funder ROR ID, a Crossref Funder ID (10.13039/100000001, its doi.org URL, or the bare digits), or a funder name — every name token must appear in one funding reference."
    • changedInput schema / properties / include_child_funders / description
      Previous value: -"Also match the ROR funder's child organizations. Only with a ROR funder."New value: +"Also match the funder's child organizations in ROR. Needs funder as a ROR ID, or a Crossref Funder ID that resolves to exactly one ROR ID; rejected with a funder name or no funder."
    • changedInput schema / properties / place / description
      Previous value: -"A geographic place phrase, matched against deposited place names."New value: +"A place name, matched anywhere inside deposited place names, so India also matches Indiana. Tried as typed, in lowercase, in uppercase, with every word capitalized, and with the first word capitalized: give a multi-word name its usual capitalization (Gulf of Mexico). For one exact, case-sensitive name, use query geoLocations.geoLocationPlace:\"Svalbard\" instead."
    • addedInput schema / properties / version_scope
      Added value: +{
      +  "description": "Which DOIs of a versioned work count. all (default): every DOI, so a Zenodo upload counts at least twice — its concept DOI and each version DOI. series: drops every record asserting IsVersionOf, so a version series counts once, through its concept DOI; a version whose concept DOI fails another filter (a later publication year, a changed creator or affiliation) or lies outside DataCite is not counted at all. releases: drops every record asserting HasVersion, so each version counts and concept DOIs drop out. Neither collapses Figshare's .vN DOIs, which point at their base DOI with IsIdenticalTo, so those pairs still count twice.",
      +  "enum": [
      +    "all",
      +    "series",
      +    "releases"
      +  ],
      +  "type": "string"
      +}
    • addedOutput schema / properties / appliedFilters / properties / version_scope
      Added value: +{
      +  "description": "Version-relation clause as sent.",
      +  "type": "string"
      +}
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `invalid_text`: Supplied nonblank text has no searchable literal clause after escaping. `invalid_query`: DataCite rejects the syntax of the query input (unbalanced parentheses or quotes, dangling operator). `invalid_filter`: A filter value is malformed: an ORCID iD failing its checksum, a ror.org or 10.13039/ value that is not a ROR ID or Crossref Funder ID, a language outside ISO 639-1, a never-assigned affiliation country code, a creator or funder with no letters or digits, a reversed year range, or include_child_funders without a ROR funder. `page_ceiling`: page × limit exceeds 10,000, or the upstream reports a page other than the one requested. `invalid_cursor`: cursor is neither \"*\" nor an envelope this tool returned, belongs to a different query or filter set, or the upstream restarted the walk. `conflicting_paging`: cursor combined with page or sort. `rate_limited`: This deployment's shared DataCite request budget is spent: its request queue could not start a request before the call's deadline, or DataCite answered HTTP 429. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `invalid_text`: Supplied nonblank text has no searchable literal clause after escaping. `invalid_query`: DataCite rejects the query input: its syntax (unbalanced parentheses or quotes, dangling operator), or a wildcard term too complex for DataCite to run. `invalid_filter`: A filter value is malformed: an ORCID iD failing its checksum, a ror.org or 10.13039/ value that is not a ROR ID or Crossref Funder ID, a language outside ISO 639-1, a never-assigned affiliation country code, a creator or funder with no letters or digits, a reversed year range, or include_child_funders with a funder name, no funder, or a Crossref Funder ID that ROR maps to no single organization. `page_ceiling`: page × limit exceeds 10,000, or the upstream reports a page other than the one requested. `invalid_cursor`: cursor is neither \"*\" nor an envelope this tool returned, belongs to a different query or filter set, or the upstream restarted the walk. `conflicting_paging`: cursor combined with page or sort. `ror_unavailable`: include_child_funders is true with a Crossref Funder ID, and ROR gave no answer to its lookup: an outage, a rate limit, a timeout, or a block page. `rate_limited`: This deployment's shared DataCite request budget is spent: its request queue could not start a request before the call's deadline, or DataCite answered HTTP 429. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "invalid_text",
      -  "invalid_query",
      -  "invalid_filter",
      -  "page_ceiling",
      -  "invalid_cursor",
      -  "conflicting_paging",
      -  "rate_limited"
      -]New value: +[
      +  "invalid_text",
      +  "invalid_query",
      +  "invalid_filter",
      +  "page_ceiling",
      +  "invalid_cursor",
      +  "conflicting_paging",
      +  "ror_unavailable",
      +  "rate_limited"
      +]
    • changedOutput schema / properties / totalCount / description
      Previous value: -"Total works matching the query and filters."New value: +"Total DOIs matching the query and filters; a versioned work counts once per DOI (see version_scope)."
  2. Changed6 schema fields changed
    • changedInput schema / properties / affiliation_country / description
      Previous value: -"ISO 3166-1 alpha-2 country of a creator or contributor affiliation, any case (DE, us). Alpha-3 codes and names are rejected."New value: +"Current or formerly assigned ISO 3166 alpha-2 country of a creator or contributor affiliation, plus XK; any case (DE, us). UK aliases to GB with a notice. Unassigned codes, alpha-3 codes and names are rejected."
    • changedInput schema / properties / limit / description
      Previous value: -"Requested rows per page, 1–10,000; values above 100 apply 100 with a notice."New value: +"Requested rows per page, a positive integer (default 20); values above 1,000 apply 1,000 with a notice unless strict limits are configured."
    • removedInput schema / properties / limit / maximum
      Removed value: -10000
    • addedInput schema / properties / limit / multipleOf
      Added value: +1
    • changedInput schema / properties / limit / type
      Previous value: -"integer"New value: +"number"
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `invalid_text`: Supplied nonblank text has no searchable literal clause after escaping. `invalid_query`: DataCite rejects the syntax of the query input (unbalanced parentheses or quotes, dangling operator). `invalid_filter`: A filter value is malformed: an ORCID iD failing its checksum, a ror.org or 10.13039/ value that is not a ROR ID or Crossref Funder ID, a language outside ISO 639-1, a creator or funder with no letters or digits, a reversed year range, or include_child_funders without a ROR funder. `page_ceiling`: page × limit exceeds 10,000, or the upstream reports a page other than the one requested. `invalid_cursor`: cursor is neither \"*\" nor an envelope this tool returned, belongs to a different query or filter set, or the upstream restarted the walk. `conflicting_paging`: cursor combined with page or sort. `rate_limited`: This deployment's shared DataCite request budget is spent: its request queue could not start a request before the call's deadline, or DataCite answered HTTP 429. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `invalid_text`: Supplied nonblank text has no searchable literal clause after escaping. `invalid_query`: DataCite rejects the syntax of the query input (unbalanced parentheses or quotes, dangling operator). `invalid_filter`: A filter value is malformed: an ORCID iD failing its checksum, a ror.org or 10.13039/ value that is not a ROR ID or Crossref Funder ID, a language outside ISO 639-1, a never-assigned affiliation country code, a creator or funder with no letters or digits, a reversed year range, or include_child_funders without a ROR funder. `page_ceiling`: page × limit exceeds 10,000, or the upstream reports a page other than the one requested. `invalid_cursor`: cursor is neither \"*\" nor an envelope this tool returned, belongs to a different query or filter set, or the upstream restarted the walk. `conflicting_paging`: cursor combined with page or sort. `rate_limited`: This deployment's shared DataCite request budget is spent: its request queue could not start a request before the call's deadline, or DataCite answered HTTP 429. Other values are possible when a failure originates below the handler."
  3. Changed3 schema fields changed
    • changedInput schema / properties / text / description
      Previous value: -"Plain words and phrases, searched literally: every query-syntax character is escaped, so \"Climate change: impacts\" works and text can never cause a syntax error. Terms are ANDed."New value: +"Plain words and phrases, searched literally: query-syntax characters are escaped, so \"Climate change: impacts\" works. Angle brackets are removed; nonblank text with no remaining searchable clause is rejected. Blank text is unset. Terms are ANDed."
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `invalid_query`: DataCite rejects the syntax of the query input (unbalanced parentheses or quotes, dangling operator). `invalid_filter`: A filter value is malformed: an ORCID iD failing its checksum, a ror.org or 10.13039/ value that is not a ROR ID or Crossref Funder ID, a language outside ISO 639-1, a creator or funder with no letters or digits, a reversed year range, or include_child_funders without a ROR funder. `page_ceiling`: page × limit exceeds 10,000, or the upstream reports a page other than the one requested. `invalid_cursor`: cursor is neither \"*\" nor an envelope this tool returned, belongs to a different query or filter set, or the upstream restarted the walk. `conflicting_paging`: cursor combined with page or sort. `rate_limited`: This deployment's shared DataCite request budget is spent: its request queue could not start a request before the call's deadline, or DataCite answered HTTP 429. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `invalid_text`: Supplied nonblank text has no searchable literal clause after escaping. `invalid_query`: DataCite rejects the syntax of the query input (unbalanced parentheses or quotes, dangling operator). `invalid_filter`: A filter value is malformed: an ORCID iD failing its checksum, a ror.org or 10.13039/ value that is not a ROR ID or Crossref Funder ID, a language outside ISO 639-1, a creator or funder with no letters or digits, a reversed year range, or include_child_funders without a ROR funder. `page_ceiling`: page × limit exceeds 10,000, or the upstream reports a page other than the one requested. `invalid_cursor`: cursor is neither \"*\" nor an envelope this tool returned, belongs to a different query or filter set, or the upstream restarted the walk. `conflicting_paging`: cursor combined with page or sort. `rate_limited`: This deployment's shared DataCite request budget is spent: its request queue could not start a request before the call's deadline, or DataCite answered HTTP 429. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "invalid_query",
      -  "invalid_filter",
      -  "page_ceiling",
      -  "invalid_cursor",
      -  "conflicting_paging",
      -  "rate_limited"
      -]New value: +[
      +  "invalid_text",
      +  "invalid_query",
      +  "invalid_filter",
      +  "page_ceiling",
      +  "invalid_cursor",
      +  "conflicting_paging",
      +  "rate_limited"
      +]
  4. Changed5 schema fields changed
    • changedInput schema / properties / licenses / description
      Previous value: -"The work's own license ids (any match), SPDX-style: cc-by-4.0, cc0-1.0, mit. Lowercased, then matched exactly; common ids: datacite_list_reference topic licenses."New value: +"The work's own license ids (any match), e.g. cc-by-4.0, cc0-1.0, cc0 1.0, mit. Trimmed and lowercased, then matched exactly, preserving internal spaces; reuse ids from the licenses facet or datacite_list_reference topic licenses."
    • changedInput schema / properties / licenses / items / pattern
      Previous value: -"^\\s*[A-Za-z0-9.+_-]+\\s*$"New value: +"^\\s*[A-Za-z0-9.+_-](?:[A-Za-z0-9.+_ -]*[A-Za-z0-9.+_-])?\\s*$"
    • changedInput schema / properties / limit / description
      Previous value: -"Rows per page, 1–100."New value: +"Requested rows per page, 1–10,000; values above 100 apply 100 with a notice."
    • changedInput schema / properties / limit / maximum
      Previous value: -100New value: +10000
    • addedOutput schema / properties / rankedCeilingReached
      Added value: +{
      +  "description": "True when ranked paging stops before all matches have been delivered; restart with cursor \"*\".",
      +  "type": "boolean"
      +}
  5. First observed

TDQS

A4.4/5.0
Behavior4/5

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

Well beyond the annotations, it discloses the counting model (a versioned work counts once per DOI), the latency cost of include_facets (2–8 s), the 1,000-row limit cap with notice, and the 10,000 page×limit ceiling. The version_scope paragraph is unusually candid about corner cases (concept DOIs failing other filters, Figshare .vN pairs still counting twice).

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

Conciseness4/5

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

Front-loaded with purpose then return shape then counting and paging caveats, so the most decision-relevant facts come first. It is dense and near the upper bound of useful length, but each sentence carries non-redundant information rather than restating the schema.

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 24 optional parameters, an output schema, and full annotations, the description covers exactly the things structured fields cannot: counting semantics, iteration strategy, and facet cost. Nothing needed to call it correctly is missing.

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 coverage is 100%, so the baseline is 3, but the prose adds real meaning: version_scope's all/series/releases semantics and their failure modes, and the cursor contract (pass nextCursor unchanged with the same query and filters) are explained outside the schema. Counting and paging interactions across page, limit, and cursor are clarified.

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?

The description opens with a specific verb and resource ("Search DataCite DOI metadata") and enumerates the research-output types covered, then states what comes back (total count plus compact rows). An agent can tell this apart from datacite_get_work or datacite_search_repositories without opening a schema.

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?

It gives concrete routing rules: text for literal words vs query for OpenSearch syntax, page for the first 10,000 ranked matches vs cursor "*" for full walks, and place vs query geoLocations.geoLocationPlace for exact case-sensitive names. It also sends the agent to datacite_list_reference for field paths and licenses. What it lacks is an explicit statement of when to prefer this over the sibling get/citation tools.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.