nobleblocks-mcp

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

Annotations already cover read-only, idempotent, non-destructive, and closed-world behavior. The description adds important non-obvious context: failures are reported per identifier rather than failing the entire batch, and each entry links to an ARK or DOI.

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 two focused sentences with no wasted wording. The batch purpose and failure behavior are front-loaded and easy to scan.

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 simple two-parameter schema, rich annotations, and an output schema, the description supplies the key remaining context an agent needs: batch behavior, format/order semantics, and partial failure handling.

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 schema already documents format options and identifier constraints. The description adds useful semantics: one format applies across all citations, the order of identifiers is preserved, and failures are listed per identifier.

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 that the tool generates citations for several papers at once in a chosen format and order. It distinguishes batch citation from single-paper workflows implicitly through 'several papers at once,' but does not name the likely sibling alternative get_citation.

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 phrase 'for several papers at once' implies this tool is for batch citation rather than a single-paper citation call. However, it does not explicitly state when to use this versus get_citation or other siblings.

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, idempotentHint=true and destructiveHint=false, so the safety profile is fully covered. The description adds useful semantics about what 'text' and 'url' actually contain, but says nothing about failure behavior for bad ids or access restrictions.

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 short sentences, front-loaded with the operation and its return shape, with zero filler. Every clause conveys information the agent can act on.

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 rich annotations, an output schema, and a fully documented parameter, the description covers the essentials of a simple single-record read. The one material omission is disambiguation from get_paper within a ten-tool sibling set.

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 the id parameter's own description ('an id from search, or any identifier get_paper accepts') already defines accepted input semantics. The tool description adds nothing further about the single parameter, so the 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 ('Fetch one paper') and enumerates the returned fields, so the operation's shape is unambiguous. It offers no differentiation from the very similar sibling get_paper, leaving the agent to guess which of the two to pick.

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?

There is no statement of when to use this tool versus alternatives, no prerequisites, and no mention of get_paper or search_papers despite both being obvious substitutes. Usage must be inferred entirely from the name and return fields.

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?

The annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the description does not need to restate safety behavior. It adds useful scope about the profile contents and most-cited papers, but it does not discuss authentication needs, rate limits, or error 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?

The definition is a single front-loaded sentence that identifies the resource, lookup key, and returned profile contents without filler. Every phrase contributes to understanding what the tool provides.

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, annotations cover the safety profile, and the input schema fully documents both parameters, so the description need not explain return structure or permissions in detail. It is complete enough to call correctly, with the main remaining gap being explicit routing guidance versus sibling tools such as search_authors.

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 already documents that ORCID may be bare or an orcid.org URL and that papers controls how many most-cited papers are included. The description mentions the ORCID lookup and cited papers, but it adds no parameter meaning beyond what the schema 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 states a specific lookup resource and key: one researcher's public profile by ORCID iD, including named fields such as affiliation, topics, metrics, NobleID, and most cited papers. It is clear what the tool returns, but it does not explicitly differentiate itself from the sibling search_authors tool.

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 phrase 'by ORCID iD' implies this tool is used when an ORCID identifier is known, which distinguishes it in practice from broad author searches. However, there is no explicit when-to-use guidance, no exclusions, and no direct reference to search_authors as the alternative for name-based lookup.

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 destructiveHint=false, so safety is covered. The description adds genuine value beyond that: it explains that the URL field holds the NobleID ARK when confirmed, else the DOI, and that unreliable DOIs are omitted rather than guessed — a real data-quality behavior an agent would otherwise not expect.

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 short sentences: the core action and formats come first, then the fallback caveat. No filler, nothing repeated for its own sake.

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, return formatting needn't be described, and both parameters are fully documented in the schema. The description covers the format choice and the identifier-resolution caveat, leaving only the relationship to the `cite` sibling unaddressed.

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 format enum is documented in the schema, so the baseline is 3. The description restates the three formats and adds context about identifier resolution into the URL, but gives no per-parameter detail beyond what the schema already supplies.

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 ("Format a citation for one paper") plus the three supported output formats, so an agent knows exactly what it produces. It does not differentiate itself from the sibling `cite` tool, which is the obvious ambiguity an agent would face here.

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 implied only: it formats a citation for a single paper, so the agent can infer it should have a paper identifier in hand. There is no explicit when-to-use/when-not-to-use guidance and no mention of the very similar `cite` sibling, leaving the routing decision to inference.

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 and idempotency, so the description's main value is the caveat that citation links are still loading and empty results should not be read as 'never cited.' That is a meaningful behavioral disclosure beyond annotations, though broader operational details are absent.

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 with zero waste. The core purpose and ordering are front-loaded, and the caveat follows naturally.

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 read-only citation lookup with full schema coverage and an output schema, the definition provides what is needed: scope, ordering, and the important caveat about loading citation links. No material gaps remain 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 identifier, limit, and offset are already well documented. The description does not add meaning beyond the schema for any parameter, so the baseline score 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 names a specific resource — papers in the NobleBlocks index that cite a given paper — and adds the sort order. It is clearly distinct from get_references or get_citation by focusing on incoming citations rather than outgoing references or citation details.

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 does not explicitly say when to use this tool versus siblings such as get_references, get_citation, or search_papers. The only guidance is an empty-result caveat, not usage selection 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 readOnlyHint=true, idempotentHint=true, openWorldHint=false, and destructiveHint=false. The description adds useful output context, including retraction status and that links.best prioritizes open access, but it does not mention not-found behavior, authentication needs, or other operational traits.

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 one front-loaded sentence with a dense but relevant field list. It is appropriately sized for a metadata retrieval tool, though the long enumeration makes it slightly heavy.

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 exists and annotations cover safety behavior, the description provides enough context about what metadata is returned. Minor operational details such as error handling are omitted but not essential 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%, and the single identifier parameter is already fully documented in the schema. The description reinforces accepted identifier types at a high level but does not add syntax or format details beyond 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 precise verb and resource: 'Full metadata for one paper or trial,' and enumerates the metadata fields returned. This clearly distinguishes it from search/list siblings such as search_papers and search_trials.

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 implied by the single-identifier retrieval model, but the description does not explicitly say when to use this instead of siblings like get_citation, cite, or fetch. No exclusions or workflow guidance are provided.

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 readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds real value beyond that: results are limited to items present in the NobleBlocks index (partial-coverage caveat) and are ordered most-cited first, both of which affect interpretation of output.

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 well-formed sentence with the subject, scope qualifier and sort order front-loaded and zero 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?

With an output schema, full parameter documentation and rich annotations, the description only needs to convey direction, index coverage and ordering — all of which it does. Minor gaps (e.g., behavior when the identifier resolves to a paper with no indexed references) are not material.

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 every parameter (identifier, limit, offset) is documented in the schema, so the description adds nothing parameter-specific. Baseline 3 applies when the schema does all the work.

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 resource and direction ('papers this paper cites (its reference list)'), which inherently distinguishes it from the reverse-direction sibling get_citing_papers. It also adds an important scope qualifier ('in the NobleBlocks index'), but it never names the sibling it is being contrasted with.

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 implicit use case is clear (retrieve a paper's reference list given an identifier), and the directional wording steers away from get_citing_papers. However, there is no explicit when-to-use/when-not guidance or named 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 readOnly, idempotent, non-destructive, closed-world behavior, so the description doesn't need to re-litigate safety. It adds one genuine behavioral fact — that `url` is open access first — but says nothing about result limits, pagination, ranking, or rate limits, so it only modestly exceeds the annotation baseline.

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 short sentences, front-loaded with the action and its distinctive output. Minor ambiguity in the trailing 'Pass an `id`' clause, which reads as if `id` were an input here.

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 rich annotations, the bar is lower and the description covers scope plus one semantic detail (open-access-first URLs). Still missing is the differentiation from the near-identical `search_papers` sibling, which is the single most decision-relevant fact an agent needs at call time.

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% for the single `query` parameter, so baseline is 3. The description adds no guidance on query syntax (boolean operators, title-only search, max 500 chars) and the second sentence about `id` refers to a parameter this tool does not have, which risks mild confusion rather than adding meaning.

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 ('Search scholarly papers') and even sketches the return shape ({results: [{id, title, url}]}), so the operation is unambiguous. However, the sibling list contains `search_papers`, and nothing in the description explains how this differs from it — an agent cannot tell the two apart from text alone.

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?

'Pass an `id` to fetch for the full text record' implies a follow-up path (the `fetch` sibling), which is useful workflow guidance. But there is no when-to-use/when-not guidance and no mention of when to prefer `search_papers`, `search_authors`, or `search_trials` instead.

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 destructiveHint=false, so safety is covered. The description adds useful context beyond that by listing the returned fields, though it says nothing about paging behavior or the access-tier cap already hinted at in 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, no waste, with the core purpose front-loaded and the routing hint trailing. Every clause 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 annotations covering safety and an output schema covering return shape, the description supplies what structured fields cannot: the sibling routing rule and a human-readable summary of results. Nothing an agent needs in order 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.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so name, limit, and offset are all documented, including the tier-cap caveat and paging semantics. The description adds no parameter-level detail beyond reinforcing that search is by name, which is the expected baseline when the schema does the work.

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 ('Find researchers by name') and enumerates what comes back (name, ORCID iD, OpenAlex id, affiliation, counts), which makes it clearly distinct from get_paper/search_papers. It also names the sibling get_author and the condition that selects it, so an agent can route without opening either 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?

Explicitly names the alternative path ('Use get_author with an ORCID iD for the profile and top papers'), giving a concrete when-to-go-elsewhere rule. It stops short of covering ambiguous-name or partial-match scenarios and does not distinguish itself from search_papers for topic-driven lookups.

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 the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds real value on top: what each result contains, the abstract-excerpt behavior, and the `best_link` fallback rule (free full text when known, else DOI/ARK). It does not mention paging interplay with `limit`/`offset` or rate/access-tier limits beyond what the schema says.

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 short sentences, front-loaded with the verb/resource and then the follow-up guidance. The middle result-field enumeration is somewhat long but earns its place by telling the agent what `id` and `best_link` are for; nothing is 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?

A 9-parameter search tool with an output schema and full parameter coverage; the description supplies the missing behavioral glue (result shape, best_link semantics, hand-off to get_paper/cite) without re-documenting parameters. Complete for a competent agent, with only paging/access-tier behavior left implicit.

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 every parameter including sort, limit, offset and the filters is already documented in structured data. The description only gestures at 'with filters' and 'keyword relevance', adding no syntax, defaults or filter semantics beyond the schema. 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 ('Search the NobleBlocks index of scholarly papers') plus the retrieval mode ('keyword relevance, with filters'), which clearly separates it from sibling tools like search_authors and search_trials by naming the object searched. An agent can identify the correct tool without opening the 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?

Explicitly routes forward: 'Use get_paper with a result's `id` for full metadata, or cite to cite it', giving concrete next-step alternatives and the condition that selects them. It stops short of stating when NOT to use this tool (e.g. versus search_authors/search_trials or search), so it is strong but not 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 readOnly/idempotent/non-destructive and closed-world, so the safety profile is covered. The description adds substantive context beyond that: results come from a curated index and are summary-level, requiring a follow-up get_paper call for the full record, and each hit carries a registry identifier. It stops short of stating result ordering or pagination behavior, so it is not 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?

Two short sentences, front-loaded with the scope statement and followed immediately by the actionable handoff. No filler or restatement of the tool name.

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 a full output schema and 100% parameter coverage, the description only needs to establish scope and the follow-up path, both of which it does. Minor gap: it does not explain how registry choice affects result content or overlap between the two sources, which matters for a multi-registry search.

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 every parameter (query, limit, offset, year_from/year_to, registry) is already documented with bounds and defaults. The description only echoes the registry sources that the enum already declares, adding no syntax or query-construction guidance beyond the schema. 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+resource ("Search clinical trial registrations") and names the two covered registries (ClinicalTrials.gov, WHO ICTRP) plus the index scope. That is clearly distinguishable from siblings like search_papers or search_authors without opening any 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?

Gives an explicit downstream routing rule: each result carries a registry id, and get_paper should be used with it for the full record. It does not contrast itself against search_papers for mixed literature/trial queries, so there is no explicit when-not guidance, but the usage context is clear.

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