orcid-mcp-server

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

Annotations already declare read-only, idempotent, and closed-world behavior, so the description adds value by specifying the return fields and the caveat that affiliation data is self-reported and absence does not mean no affiliation. This warns the agent about data completeness and accuracy, which goes beyond the 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 concise (four sentences) and front-loaded with the primary purpose. It then covers parameter behavior, return data, and a data-quality caveat—each sentence serves a distinct purpose without redundancy or fluff.

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 tool's low complexity (2 params, one required), the presence of an output schema, and comprehensive annotations, the description fully covers what the tool does, what it returns, and a critical data limitation. It provides all necessary context for correct selection and invocation.

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%, with both 'types' and 'orcid_id' fully documented. The description's explanation of 'types' and its default mirrors the schema, adding no new information. Since the schema already provides complete parameter semantics, the description does not need to compensate, resulting in a baseline score 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?

The description opens with a specific verb ('Fetch') and a specific resource ('affiliation records for an ORCID researcher'). It is immediately distinguishable from sibling tools by focusing on affiliation data, as opposed to funding, peer reviews, or 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 clearly implies when to use this tool: when affiliation data for an ORCID researcher is needed. It provides details on the 'types' parameter and default behavior, which helps an agent decide if this is the right endpoint, though it does not explicitly name alternatives or give exclusion criteria.

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 mark the tool as readOnly and idempotent, so the description does not need to reiterate those. It adds valuable behavioral context that funding data is entirely self-reported and often missing, which is a critical reliability caveat beyond what annotations convey. 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 concise and well-structured: a lead sentence states purpose and scope, a second sentence lists return values, and the final sentences provide essential caveats. Every sentence adds value without redundancy, making it easy for an agent to parse quickly.

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?

An output schema exists, so detailed return formatting is covered there. The description complements this with high-level return categories and the crucial caveat about self-reported data, which helps the agent interpret missing results correctly. It is complete for a simple read-only tool with one parameter.

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 for the single parameter (orcid_id) is 100%, with detailed format guidance and examples. The description does not add semantics beyond the schema's parameter explanation, which is the baseline for high schema coverage. No parameter information in the description is needed.

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 clearly specifies an action ('Fetch funding records') and a resource ('ORCID researcher') with a defined scope ('grants, contracts, awards, and salary awards'). It also lists concrete return fields (funder names, grant numbers, funding periods), which distinguishes it from sibling tools like orcid_get_affiliations or orcid_get_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 context on when to use this tool by enumerating the funding-related content and emphasizing high-value use cases like grant tracking and funder analysis. It also gives a caveat about self-reported data, implicitly guiding expectations about real-world usage. However, it does not explicitly name alternatives or state 'when not to use,' so it falls short of a perfect 5.

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 cover readOnlyHint and idempotentHint, so the safety profile is clear. The description adds valuable context about data provenance: 'Peer review records are self-reported or imported by participating publishers — coverage varies by researcher,' which helps interpret results and sets expectations.

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, front-loaded with the main action, and every sentence adds value. The first sentence defines the tool, the second gives use cases, and the third provides a caveat. No fluff or redundancy.

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?

With an output schema present and only one parameter, the description is complete for this simple read-only tool. It covers purpose, usage, and data caveats without needing to explain return format, which is already in the output schema.

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 documents the single parameter orcid_id with pattern and description (schema coverage 100%). The description does not add further parameter-level detail, so the baseline score of 3 is appropriate; no missing semantics to compensate.

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 explicitly states the tool fetches peer review activity for an ORCID researcher, listing specific fields like convening organizations, reviewer role, review type, and completion dates. It clearly distinguishes from sibling tools such as orcid_get_works or orcid_get_affiliations by focusing on peer reviews.

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: 'Use to assess editorial activity, journal affiliations, and the scope of a researcher's peer review contributions.' It does not explicitly mention alternatives or when not to use, but the context is specific enough to guide tool selection.

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 agent knows it's a safe read. The description adds a meaningful behavioral trait: the profile contains only publicly visible data because researchers control visibility per field. This goes beyond the annotations and helps the agent set expectations about data completeness.

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 earning its place: the first lists what the profile contains, the second provides usage context as the entry point, and the third covers input formats and public-visibility behavior. No wasted words, and the most important information is 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?

Given the tool has a single parameter, a rich output schema, and annotations indicating a safe read operation, the description fully covers what an agent needs: the resource being fetched, contents, usage context, input format, and visibility constraints. Nothing essential is missing for correct selection and invocation.

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%, and the schema's description for orcid_id already explains the bare format and full URI. The description essentially repeats this information without adding new semantic value, such as examples of invalid inputs or behavior for non-existent IDs. Baseline 3 is appropriate since the schema carries the parameter documentation burden.

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 clearly states the tool fetches a researcher's public profile from ORCID and lists specific contents (name, biography, keywords, URLs, external identifiers). This distinguishes it from sibling tools that fetch specific sections like affiliations or works, and it is explicitly positioned as the entry point for building a researcher dossier.

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 says 'This is the entry point for building a researcher dossier,' which implies when to use it (first, to get the general profile) versus siblings that retrieve specific sections. It does not explicitly name alternatives or provide when-not-to-use guidance, but the context is clear enough for an agent to select it appropriately.

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 description's disclosure of the return fields (title, hosting organization, external identifiers, access period) and the typical deposition source adds value beyond structured metadata. It also does not contradict annotations; the description's 'List' aligns with read-only behavior.

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 states the core purpose and scope, the second sets expectations about data scarcity, and the third clarifies provenance and return fields. No filler or repetition of schema/annotation information.

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 tool has a single parameter, a full output schema, and clear annotations, the description goes beyond the minimum by explaining the return contents, the typical source of entries, and the likelihood of empty results. This covers what an agent needs to select and interpret the tool correctly among many ORCID siblings.

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 for orcid_id already provides a descriptive comment and a detailed pattern, resulting in 100% schema description coverage. The tool description does not add parameter-specific guidance beyond restating that resources are associated with the ORCID researcher, 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 opens with a specific verb ('List') and resource ('research resources associated with an ORCID researcher'), immediately distinguishing it from sibling tools like affiliations, funding, or works. It enumerates concrete subtypes (compute allocations, equipment access, lab facilities, data resources, clinical study registrations) which makes the scope 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 context about ORCID research resources being a newer, sparsely populated section and that most entries come from allocation systems (ACCESS, XSEDE) gives useful expectations for when to invoke this tool. It does not explicitly name alternatives or exclusion criteria, but the resource-specific scope and sibling tool names make the intended use 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?

Beyond the readOnlyHint and idempotentHint annotations, the description discloses important error-handling behavior: per-record failures are surfaced as error entries instead of failing the whole call. It also lists what fields are returned, adding practical context beyond the 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?

Four sentences, with the main action front-loaded. Each sentence carries information, though the third sentence lists many return fields and is somewhat long. Still, it is efficient and avoids unnecessary words.

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 description covers the request scope (1–100), the source of identifiers, the return content, and error behavior. Given that an output schema exists and annotations declare the tool read-only/idempotent, this is nearly complete. It does not mention authentication, but the annotations imply a safe read operation.

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 covers both parameters with full descriptions (pattern for orcid_id, array constraints for put_codes). The description adds the workflow hint about get_works, but this duplicates what the schema already says for put_codes, so it does not materially enhance parameter understanding.

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 action ('Fetch full detail records for 1–100 works') and identifies the resource precisely (works by put-codes). It clearly differentiates from siblings like orcid_get_works, which lists works, because the tool fetches full detail records for specific put-codes.

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 connects to orcid_get_works by explaining that put-codes come from that tool, implying a workflow. However, it does not explicitly state when to avoid using this tool (e.g., for a single work) or name alternatives, though the singular/bulk distinction is 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?

Beyond the readOnlyHint and idempotentHint annotations, the description adds valuable behavioral nuance: the 50-default with paging via workCount and nextOffset, the self-reported nature of works (researcher may not have linked everything), and the chaining potential of external IDs. This is independently useful context that complements the annotations without contradicting them.

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 efficiently compact: six sentences that each carry operational or decision-relevant information. It is front-loaded with the main purpose, then covers defaults, paging, payload customization, and related tools without redundancy or 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?

Given that an output schema exists, the description needn't itemize return fields. It covers the key behavioral aspects (default limit, paging, payload option), caveats about data completeness, and integration paths (chaining identifiers, getting details). This is complete for a list tool of this complexity.

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 describes all four parameters at 100% coverage, including semantic details like 'full list is sliced locally' and how offset works. The description echoes these details (e.g., 'the returned nextOffset') but doesn't add a new layer of parameter meaning beyond what the schema provides. Per the rubric, baseline 3 is appropriate when the schema does the heavy lifting.

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 ('Retrieve') and a clear resource ('works associated with an ORCID iD'), immediately distinguishing it from sibling tools. It further disambiguates by enumerating content types (publications, datasets, software, preprints) and explicitly noting it returns summaries rather than full records.

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 strong context for when to use this tool: listing works, with default pagination behavior and an option to lighten the payload. It names a specific alternative (orcid_get_work_detail) for full records, but it does not explicitly contrast with all siblings like affiliations or funding tools. This is clear context, but not a comprehensive when/not-when guide.

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?

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses specific behavioral traits: returns ranked candidates with a default and maximum count, provides transparent disambiguation signals (name match type, institution overlap, anchor usage), and explicitly states that no synthetic scores are used — only raw signals. This adds meaningful operational transparency not captured by the 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 four sentences, tightly packed with useful information. It front-loads the core action, then explains return characteristics, signals, usage guidance, and a note on methodology, with zero filler. 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?

With an output schema present, the description need not detail return types, but it still explains what signals the output will contain. It covers purpose, usage context, parameter interplay (anchor near-determinism), and even warns about synthetic scores. For a moderately complex tool with 5 parameters, this description is exceptionally complete.

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 the baseline is 3. The description adds nuance to the DOI/PMID parameters by explaining they are 'near-deterministic' anchors that filter to researchers who linked the work to their ORCID record. It also clarifies the rows parameter's default and range, which is partially redundant but reinforces the schema. The extra semantic context about anchor behavior justifies a 4.

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 combo: 'Disambiguate an author name to a verified ORCID iD.' It clearly distinguishes this tool from its sibling orcid_search_researchers by stating it provides ranked disambiguation for ambiguous names. The purpose is unambiguous and directly tied to the tool's name.

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 says 'Use this tool (not orcid_search_researchers) when the input is an ambiguous name that needs ranked disambiguation.' This directly answers when to use vs. alternatives, adding a clear exclusion and naming the alternative. It also provides guidance on the DOI/PMID anchor as a near-deterministic filter, further informing usage.

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, but the description adds crucial behavior: 'All provided structured params are ANDed together,' 'The `query` field appends raw Solr syntax,' 'Returns ORCID iDs with inline name and institution data,' and the Public API caps results at 10,000. This goes far beyond the annotation 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 four sentences, front-loaded with purpose, then composition semantics, response value, alternative, and API limit. Every sentence delivers necessary information with zero redundancy.

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?

With an output schema present and strong annotations, the description covers the essential search semantics, pagination constraint, and when to use an alternative. The mention of inline data retrieval and the ANDing rule fills gaps that the schema alone cannot express, making it complete for a search tool.

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 schema has 100% per-parameter descriptions, but the tool description adds interaction meaning not in the schema: structured params are ANDed, and the `query` field appends to the generated clause. This clarifies how parameters combine, raising it above the baseline 3 for high coverage, though individual param formats remain schema-driven.

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 'Search the ORCID registry using structured field parameters or raw Solr syntax,' clearly stating the verb, resource, and two search modes. It distinguishes itself from sibling orcid_resolve_researcher by positioning search as for broad queries and resolve as for ranked disambiguation.

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 explicit guidance: 'For ranked disambiguation of an ambiguous author name, use orcid_resolve_researcher instead,' naming the alternative and when to choose it. It also advises pagination for the 10,000-result cap and explains when no follow-up profile fetches are needed, providing clear context for when this tool suffices.

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