orcid-mcp-server

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is known. The description adds a valuable behavioral note that affiliation data is self-reported and that absence does not imply no affiliation, which is critical for correct interpretation. It also mentions the specific fields returned (organization names, identifiers, etc.), enriching the behavioral context beyond 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 three sentences, each carrying weight: purpose, parameter control, and data caveat. It is front-loaded with the primary action and remains free of redundant phrasing. Every sentence earns its place without padding.

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 tool is a straightforward read operation with an output schema available. The description covers the purpose, parameter behavior, returned fields, and a crucial data-quality caveat. There is no missing information an agent needs to invoke it correctly or interpret results appropriately.

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?

Input schema covers 100% of parameters with descriptions, so the baseline is 3. The description reinforces the types parameter's meaning by listing all acceptable values and the default, and adds context on what the returned data contains. It slightly exceeds the schema by explaining the output fields, but does not add significant new param-level semantics beyond what the schema already provides.

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 uses a specific verb ('Fetch') and resource ('affiliation records for an ORCID researcher'), and clearly differentiates from sibling tools by focusing on affiliations. It states the exact scope and lists the types parameter's possible values, leaving no ambiguity about what this tool retrieves.

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 clear context on when to use this tool (to fetch affiliations) and explains the default behavior of the types parameter. However, it does not explicitly reference sibling tools or state when to choose an alternative (e.g., if needing funding or peer reviews), so the 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.

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

Annotations declare openWorldHint=false, meaning absence of a value implies absence in the real world (closed-world). The description explicitly states the opposite: 'Absence of funding records does not imply absence of funding' — the open-world position. This directly contradicts the annotation, giving the agent conflicting guidance on how to interpret missing data.

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?

Five sentences, each earning its place: purpose, return fields, the self-reporting caveat, the absence implication, and the value statement. Purpose is front-loaded and the caveat is placed before the value claim for logical flow. No 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 single-parameter read-only tool with a full output schema, this is complete. It states what it returns, warns about data incompleteness, and explains when the results are valuable — an agent can invoke it and interpret the response 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 100% for the single orcid_id parameter, including the pattern and accepted formats (bare or full URI). The description adds no further parameter details, so it neither raises nor lowers the baseline of 3.

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?

States a specific verb and resource ('Fetch funding records for an ORCID researcher') with enumerated record types (grants, contracts, awards, salary awards) and the returned fields (funder names, org identifiers, grant numbers, funding periods). The funding focus clearly differentiates it from siblings like orcid_get_works and orcid_get_affiliations.

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?

Provides clear interpretive context: funding data is 'entirely self-reported' and 'high-value for grant tracking and funder analysis'. It tells the agent when results are meaningful, though it does not explicitly contrast with sibling tools or state when to prefer an alternative.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and idempotentHint=true. The description adds a meaningful behavioral caveat: 'Peer review records are self-reported or imported by participating publishers — coverage varies by researcher.' This discloses potential data incompleteness, which is not captured in annotations and is important for interpreting results. No contradiction with annotations exists.

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 three concise sentences with zero redundancy. The first sentence front-loads the core purpose and field list, the second states the use case, and the third provides an essential data-quality caveat. Every sentence adds value, and the structure is tight and scannable.

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 getter with one fully-documented parameter and an existing output schema (which obviates the need to explain return values), the description covers all essential context: what the tool retrieves, when to use it, and a critical caveat about data coverage. Nothing an agent needs to decide whether and how to call it is missing.

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 100%; the single parameter orcid_id is fully documented in the schema (format, bare URI, pattern). The description does not add additional parameter semantics beyond what the schema already provides. Since the schema carries the full burden, 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 ('Fetch') and resource ('peer review activity for an ORCID researcher') and enumerates the exact data points returned (convening organizations, reviewer role, review type, completion dates, ISSN-keyed group identifiers). This clearly distinguishes it from sibling getters like orcid_get_works or orcid_get_affiliations, which target different record types. The scope is unambiguous.

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 a clear use case: 'Use to assess editorial activity, journal affiliations, and the scope of a researcher's peer review contributions.' This tells an agent when to invoke the tool, but it does not explicitly contrast with alternatives (e.g., 'use this instead of works for review data'). Given the sibling names are self-explanatory, the lack of explicit exclusions is minor but still leaves the when-not-to-use guidance implicit.

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

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 a valuable behavioral trait not in annotations: 'The profile contains only publicly visible data — researchers control visibility per field.' This informs the agent about data availability and privacy constraints, which is beyond the structured 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 with zero waste. The first sentence states the purpose and contents, the second provides strategic context, and the third covers input formats and visibility. All information is pertinent and effectively 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?

The tool has one well-documented parameter, an output schema (so return values are covered), and the description explains what data is included and its public-only nature. There are no nested objects or additional complexity, and the description fully prepares an agent to call this tool 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% — the schema description already explains both accepted formats (bare ORCID iD and full URI) and the pattern enforces it. The description repeats this exact information without adding new meaning. Since the schema does the heavy lifting, a 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 (Fetch) and resource (researcher's public profile from ORCID) and enumerates the included fields (name, biography, keywords, researcher URLs, external identifiers). It also positions itself as 'the entry point for building a researcher dossier,' which clearly differentiates it from sibling tools focused on specific sections like affiliations or funding.

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 explicitly calls this 'the entry point for building a researcher dossier,' implying you should start here before using more specific sibling tools. However, it does not explicitly name alternatives or state when NOT to use this tool, leaving the routing logic to inference. This is a clear context but lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description need not restate those. It adds valuable context beyond annotations: the section's newness, the likelihood of empty results, the typical deposition source, and the specific return fields (title, hosting organization, external identifiers, access period). This helps the agent set expectations without contradicting any annotation.

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 three sentences with no redundancy. It leads with the main verb and resource, then packs useful contextual details and return fields into a compact structure. 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 single-parameter read tool with annotations and an output schema, the description is complete: it defines the tool's purpose, the data's typical state (mostly empty), who deposits it, and what the response contains. An agent can decide whether to call it and what to expect without further inference.

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 already provides 100% coverage for the single parameter 'orcid_id', including format and accepted URI or bare forms. The tool description adds no additional parameter-level meaning beyond what the schema documents, 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 ('List') and a precise resource ('research resources associated with an ORCID researcher'), and enumerates the exact types included (compute allocations, equipment access, lab facilities, data resources, clinical study registrations). It also distinguishes this from sibling tools by referencing the ORCID section, making the tool's purpose unmistakable.

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 clearly scopes usage to research resources and adds practical guidance: it's a newer section, most researchers have no entries, and deposits come from resource-allocation systems like ACCESS and XSEDE. It does not explicitly name alternatives or state when not to use it, but the sibling names (affiliations, funding, works) and the focused description make the usage context clear.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, which covers the safety profile. The description adds genuine behavioral value beyond that: per-record errors for not-found or inaccessible put-codes are surfaced as error entries rather than failing the whole call. It also enumerates the returned fields (abstract, CRediT contributors, external ID list, citation metadata, journal, URL). No contradiction exists — 'Fetch' aligns with readOnlyHint.

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 four-sentence paragraph that front-loads the core action in the first sentence and then builds detail. Every sentence earns its place: scope, input provenance, returned fields, and error behavior. It is informative without being bloated, though slightly dense in the field-enumeration sentence.

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 an output schema exists and the input schema is fully self-describing, the description covers the essential operational context: batch limits, the dependency on orcid_get_works, per-record error handling, and the return payload composition. No critical gap prevents an agent from calling it correctly, though it could optionally name the output schema structure explicitly.

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%, so both parameters are fully documented in the schema, giving a baseline of 3. The description adds value on top by explaining that put_codes are sourced from the putCode field of orcid_get_works responses, providing provenance guidance that the schema alone lacks. This linkage helps the agent know where to retrieve the required input.

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 opens with a specific verb and resource: 'Fetch full detail records for 1–100 works by their put-codes in a single request.' It clearly scopes the tool to bulk work detail retrieval, and distinguishes it from siblings by naming the input mechanism (put-codes) and the parent tool (orcid_get_works) that supplies them. An agent can immediately tell this apart from orcid_get_works, orcid_get_affiliations, or orcid_get_funding.

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 an implicit workflow: 'Put-codes are returned by orcid_get_works in the putCode field of each work entry,' which tells the agent that this tool depends on a prior orcid_get_works call. This provides clear contextual guidance on when to invoke the tool. However, it offers no explicit exclusions or 'use X instead of Y when' routing for the other siblings (affiliations, funding, peer reviews), so the guidance is implied rather than stated.

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

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

Annotations only declare readOnlyHint, openWorldHint, and idempotentHint. The description adds substantial behavioral context: default paging behavior (first 50, workCount total, nextOffset), how limit and offset interact, the option to slim payloads, chaining readiness of external IDs to Crossref/PubMed/arXiv, and the caveat that works are self-reported and may be incomplete. This goes far beyond the safety hints.

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 about four sentences, front-loaded with the core purpose and immediately followed by return details, paging, chaining, and a data-quality caveat. Every sentence adds distinct value; there is no fluff, redundancy, or irrelevant detail. The structure guides the agent from what it does to how to page and what to expect.

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 output schema and annotations are present, the description covers everything an agent needs to call correctly: what fields are returned, how to page with offset/limit/nextOffset, how to get full details via orcid_get_work_detail, how to chain external IDs, and the self-reporting limitation. No missing operational or safety details were identified.

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%, so each parameter is fully documented in the schema. The description adds value by clarifying the paging interaction ('the full list is sliced locally'), the default and max for limit, the purpose of include_external_ids as a payload optimization, and the two accepted formats for orcid_id. This is more than a mere restatement, justifying an elevated score above the baseline.

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 opens with a specific verb-resource pair, 'Retrieve works associated with an ORCID iD,' and enumerates content types (publications, datasets, software, preprints) along with returned fields (put-codes, titles, types, dates, journal names, external IDs). It clearly distinguishes from siblings like orcid_get_work_detail (by referencing it for full records) and other resource-specific tools (affiliations, funding, etc.) through the focus on works.

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 clear usage context: it explains default limit of 50, paging with offset and nextOffset, the option to reduce payload with include_external_ids, and explicitly routes to orcid_get_work_detail when full records including abstracts are needed. It lacks an explicit 'do not use when' statement, but the alternative path is explicit enough that an agent can choose correctly.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint) already signal safety, but the description adds substantial behavioral context: ranked results, disambiguation signals (name match type, institution overlap, DOI/PMID anchor), and 'No synthetic scores are used — raw signals only.' This goes well beyond the annotation hints and fully discloses internal logic.

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 earning its place: the first defines the core action and output, the second explains the return signals, the third gives usage guidance and disambiguation philosophy. No filler, front-loaded with the primary purpose.

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 presence of an output schema, the description doesn't need to detail return format beyond what it already provides. It covers all necessary call context: when to use, what parameters matter (DOI/PMID anchors), and what results contain. Nothing an agent needs to invoke the tool correctly is missing.

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 each parameter has a description, so baseline is 3. The description adds meaningful extra semantics: explains the near-deterministic anchor behavior for doi/pmid, the default and max for rows, and preference for full names in the name parameter. This elevates it above baseline but doesn't reinvent the schema.

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 clear verb and resource: 'Disambiguate an author name to a verified ORCID iD.' It also explicitly distinguishes itself from the sibling orcid_search_researchers by stating when to use it instead, which makes the purpose unambiguous.

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?

Provides explicit when-to-use guidance: 'Use this tool (not orcid_search_researchers) when the input is an ambiguous name that needs ranked disambiguation.' Also clarifies the near-deterministic nature of DOI/PMID anchors, giving concrete selection criteria beyond basic alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the description's added behavior around the API cap (10,000) and pagination requirement, plus the return of inline data, meaningfully extends this. No contradiction with annotations. It does not mention error cases, but given annotations, this is adequate.

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 ~120 words but every sentence carries weight: purpose, semantics, return format, alternative, and limit are all addressed. The most critical usage distinction (sibling alternative) is placed near the end but is clearly flagged. No redundant language.

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 tool has 10 optional parameters and an output schema, and the description covers how parameters combine, what the response shape is (inline data), and the pagination cap. It also directs to the correct sibling for a specific scenario. Nothing essential is missing for an agent 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?

The input schema fully describes each parameter (100% coverage), but the description adds critical combination semantics: structured params are ANDed, and the query field appends raw Solr syntax. This shared behavior isn't evident from the schema alone and helps the agent construct correct queries.

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 the ORCID registry' using structured parameters or raw Solr. It clearly differentiates from sibling get_* tools by focusing on search and explicitly names orcid_resolve_researcher as an alternative for a different use case. The return value (ORCID iDs with inline name/institution) is also clarified.

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 explicitly instructs to use orcid_resolve_researcher when ranked disambiguation of an ambiguous name is needed, providing a clear when-not. It mentions pagination for large result sets, which guides the agent on handling large queries. The note about no follow-up fetches for basic disambiguation suggests this tool is the first step, with get_* tools for details.

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