datacite-mcp-server

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

Annotations already cover safety (readOnly, idempotent, openWorld), and the description adds substantive behavior: unsupported or dependent journal styles are rejected rather than silently falling back to APA, text is returned as plain text plus upstream HTML markup, and a DOI held by another agency yields found: false with the agency named. That is exactly the kind of failure-mode disclosure an agent needs.

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?

Front-loads the core action and output modes, then adds error handling and return-shape notes in separate sentences. Dense but every sentence carries information; the only cost is a slightly packed opening clause listing all formats.

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 values, yet it still notes the plain-text-plus-HTML shape and the found:false case. Combined with complete schema coverage and annotations, nothing material is missing for correct 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%, so the baseline is 3; the description adds some value by explaining the default (APA/en-US), that style ids are lowercased, and by pointing to datacite_list_reference for verified style and locale ids. Most parameter detail, however, is already carried by 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?

States a specific verb ('Render') plus resource ('one DataCite DOI') and enumerates both rendering modes (formatted citation vs. machine-readable record) with the exact format list. An agent can tell this apart from datacite_get_work, which returns the work record rather than a citation rendering.

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?

Explains defaults (APA in US English), what the style parameter controls, and what happens with unsupported styles or DOIs DataCite does not hold. It stops short of explicitly naming a sibling to use instead when the agent wants raw metadata, but the usage context is otherwise 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 cover read-only, open-world and idempotent, and the description still adds substantial behavior: long lists are capped with exact list/offset continuation recipes, and a DOI not held by DataCite returns found: false naming the responsible registration agency. That describes both truncation and the miss case, which annotations cannot express.

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?

Front-loaded with the core action and dense with specifics; the field enumeration is long but each item tells the agent what is retrievable. Could be tightened by grouping the field list, but no sentence is pure 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 an output schema exists, return value shape need not be explained, and the description still covers the two things the schema cannot: truncation/continuation and the not-found outcome. For a 3-parameter read tool with full schema coverage, nothing an agent needs to invoke it 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%, so the baseline is 3; the description earns a bump by explaining the purpose of `list`/`offset` — page one list while other fields keep default caps — which is the rationale behind the parameter pair rather than a restatement. DOI format handling is left entirely to the schema, which is reasonable given the regex and example there.

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 full deposited DataCite metadata for one DOI — and enumerates the payload scope (titles, creators with ORCID/ROR, funding, related identifiers, counts). It also positions itself against datacite_trace_relations, so an agent can separate this record-fetch tool from the graph traversal sibling.

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?

Usage is clear from context: call it with a DOI when the full record is wanted, and pass `list` to page one capped list without losing the rest. It also routes graph-shaped queries to datacite_trace_relations and out-of-scope DOIs to the named registration agency. It never explicitly contrasts with datacite_search_works or datacite_get_citation, so the sibling differentiation is partial rather than complete.

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, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds genuine context on top: "Offline; makes no upstream request" confirms no network/rate cost, and it mentions that coverage includes rate-limit and paging rules. It does not describe output shape, though an output schema 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?

Front-loaded with the core purpose, then one dense but readable enumeration that mirrors and slightly annotates the enum values, closing with the useful offline note. The list is long, but each item maps to a real topic an agent can request, so it mostly 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-enum-parameter reference tool with a full output schema, the description covers purpose, scope, and the offline/no-request behavior. An agent has everything needed to invoke it correctly, with only minor gaps (no mention of response size or caching expectations).

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 enum's own description already spells out the tricky topics (identifier_types vs identifier_formats, query_syntax, coverage). The prose enumeration in the description largely mirrors the enum values, adding only grouping detail such as 'relation types with their inverses and groups'. Baseline 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?

States a specific verb (look up) and resource (controlled vocabularies and identifier forms), scoped to what the sibling datacite_* tools accept. An agent immediately understands this is the offline reference/dictionary tool, distinct from the search/get/trace siblings.

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?

Makes the usage context clear by tying the lookup to the inputs other datacite_* tools require ("the identifier forms the other datacite_* tools accept"), which implicitly recommends calling it before those tools. It stops short of explicit when-not-to-use or step-ordering guidance.

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 read-only, idempotent, open-world behavior, so the safety bar is low. The description adds the valuable cross-tool contract — the returned repositoryId is exactly the value datacite_search_works accepts in repository_ids — plus a summary of the payload fields. Pagination caps and the >100 limit behavior are left to the schema.

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?

Two sentences, front-loaded with the capabilities and ending with the routing tip. The second sentence is long but every clause — facet ranking, top ten, counts — carries actionable 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?

With an output schema and full annotation coverage, the description only needs to cover purpose, alternatives, and cross-tool wiring, all of which it does. Return-shape details are partially restated but the mode-switching caveats live in the schema rather than the prose.

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 parameters are thoroughly documented there, including the rule that ID lookup ignores query and filters. The description's filter list and ID-lookup mention largely mirror the schema, so it clears the baseline but adds little parameter-level meaning beyond it.

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 (find/look up) and resource (DataCite repository accounts) and enumerates the filter dimensions, so an agent immediately knows the surface. It is clearly distinct from datacite_search_works, whose repository_ids parameter it feeds the repositoryId into.

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 names both modes (filter search vs. ID lookup) and gives an explicit alternative-with-condition: to rank repositories by work counts on a topic run datacite_search_works with include_facets: true and read the repositories facet. Nothing is left to inference about which sibling to call.

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 safety (readOnly, idempotent, openWorld), and the description adds real behavioral context: result rows are compact with named fields, facets are optional, and pagination is either ranked-page (bounded at 10,000) or registration-order cursor walk. The latency note for facets also exists in the schema, so part of this is restated rather than new, keeping it below a 5.

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 the capability statement front-loaded, followed by the filter menu and then the return/pagination contract. The middle sentence is a long enumeration that overlaps the schema, but every clause helps an agent recognize whether the filter it needs exists.

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 23-parameter search tool with annotations and an output schema, the description covers the essentials: query modes, filter surface, return shape, facet cost, and both pagination strategies with their bounds and mutual exclusions. It also cross-references the tools that supply valid repository/provider ids and vocabularies, so nothing blocking a correct call 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% and each parameter already documents its accepted forms, so the baseline is 3. The description adds only a synthesis—filters are ANDed with text/query and array filters accept any match—which is modest value beyond the per-parameter docs.

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: searches DataCite DOI metadata for datasets, software, samples, workflows and other research outputs, which makes the scope of the corpus obvious. It does not name a sibling, so an agent must infer the split with datacite_get_work (single DOI lookup) and datacite_search_repositories (provider/repository discovery) rather than being told.

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?

Gives concrete operating guidance: combine `text` (literal) or `query` (OpenSearch syntax) with filters, use page numbers only within the first 10,000 ranked matches, and pass cursor "*" to walk the full set. It points to datacite_list_reference for syntax and controlled vocabularies. It never states when to prefer a sibling over this tool, so the routing is only implied.

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?

Despite annotations already declaring readOnly/openWorld/idempotent, the description adds real behavioral context: depth cap of 2, node-cap default and ceiling with a notice when it binds, hydration rules for DataCite vs non-DataCite identifiers, single-page event reads with ordering that can change, and the caution that an absent edge is not evidence of no relationship. That is disclosure beyond the structured fields.

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?

Front-loaded with the core action and organized as purpose → DOI acceptance → hydration/caps → caveat. It is dense but not padded, though it re-states depth and node-cap defaults that the schema already carries and lists relation categories at unnecessary length in the opening 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?

For a six-parameter, multi-mode graph tool with an output schema, the description covers the node/edge model, truncation disclosure, second-hop behavior, pagination continuation, and the key epistemics caveat. Nothing an agent needs to invoke it 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 description coverage is 100%, so the schema already explains doi, depth, max_nodes, event_offset, relation_types and include_event_data in detail. The description largely restates the depth and node-cap defaults rather than adding syntax or semantics the schema lacks; baseline 3 applies.

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 — 'Map the relation graph around one DOI' — and enumerates the scope (versions, parts, supplements, derivations, citations, references). An agent can tell this multi-hop graph tool apart from singular-record siblings like datacite_get_work and datacite_get_citation 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.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Use cases are implied ('find the datasets and software it cites and those that cite, supplement, or derive from it') and the event-data-only mode trigger is explained, but no sibling is ever named as an alternative and no when-not-to-use condition is given. Usage must be inferred from the described behavior.

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