Research intensity for 118 elements and topics, ~10M papers. Free element scores; x402 pay-per-call.
Scored across 9 tools
Four tools return ranked papers (get_element_papers, get_subject_papers, lab_run, research) and three return RI/RIS-type metrics (get_element_ri, get_subject_ri, get_subject_history), so boundaries require careful reading. Descriptions do try to separate element vs. topic vs. broad question, but 'get_element_papers' vs 'get_subject_papers' is a subtle distinction an agent could easily misselect. The lab_quote/lab_run pair is well-differentiated.
get_element_* and get_subject_* follow a clean get_X pattern, but research (bare verb), search_subjects, and the lab_quote/lab_run pair break the convention. The result is readable but mixed verb/prefix styles across the set.
Nine tools is well within the 3-15 sweet spot for a research-literature and metrics server. Each tool maps to a plausible operation (resolve, papers, metrics, history, boolean quote, ranked run) without obvious filler.
The surface covers the core flow: resolve a subject, get its papers and RI/RIS/HRI, pull history, run boolean scoped searches and broad literature questions. Minor gaps exist (no pagination, capped at 100 papers; no author/venue-level operations), but these are workable limitations rather than dead ends.
The top papers for one element, narrowed with keyword to one of its materials or applications (e.g. symbol='Al', keyword='aluminum nitride'; the keyword must name one of the element's topics exactly, case aside -- search_subjects finds topic names). Returns title, DOI, venue, year, citations. sort=impact (default) favours recent, well-cited work; sort=foundational gives the most-cited classics; sort=newest the latest. Each paper carries its abstract where one is on file (about 6 in 10). Requires a Personal+ account. Capped at 100 papers with no pagination. Without a key, pay per call: $0.02 for up to 20 papers, $0.10 for up to 100, in USDC on Base or Solana via x402 (send the payment in _meta["x402/payment"]).
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | impact = citation-impact ranking (default); newest = most recently published first; foundational = most-cited first (the classics a reading list starts from). | impact |
| limit | No | ||
| symbol | Yes | Element symbol, e.g. 'Fe' (a name like 'Iron' or an atomic number like '26' also works) | |
| keyword | No | Optional: narrow to one application keyword. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so well: discloses ~60% abstract availability, the Personal+ account requirement, the 100-paper cap with no pagination, and the full pay-per-call pricing plus x402 payment mechanics. These are exactly the operational facts an agent needs to avoid failure.
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?
Dense but front-loaded: purpose and the keyword constraint come first, then sort behavior, then account/cap/pricing. Every clause earns its place, though the single-paragraph form makes the pricing and return-field details slightly hard 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?
With no output schema, the description compensates by naming returned fields (title, DOI, venue, year, citations) and abstract coverage. Auth, limits, ranking modes, and payment paths are all covered, so an agent has what it needs to call 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 75%, and the description adds genuine meaning beyond it: keyword must exactly match a topic name (case-insensitive) and can be found via search_subjects, plus per-sort behavioral descriptions of impact/foundational/newest. The limit parameter's semantics are covered mainly by the cap note rather than explained directly.
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?
Opens with a specific verb+resource ('top papers for one element') and immediately scopes it via the keyword parameter to materials/applications. The element-vs-subject distinction is implied clearly enough to separate it from get_subject_papers, and the returned fields are named.
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 explicit guidance on the keyword requirement ('must name one of the element's topics exactly, case aside') and routes to search_subjects for discovering topic names. It stops short of stating when to prefer this over the sibling get_subject_papers, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get current Research Intensity (RIS) for one of the 118 chemical elements, with a citation URL. No API key needed. Historical RI (HRI) is included with a Personal+ key.
| Name | Required | Description | Default |
|---|---|---|---|
| symbol | Yes | Element symbol, e.g. 'Fe' (a name like 'Iron' or an atomic number like '26' also works) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does a decent job: it discloses that the current RI needs no API key, that a citation URL is returned, and that historical RI (HRI) is gated behind a Personal+ key. It omits rate limits and explicitly confirming the read-only nature, but the access/tier disclosure is genuinely useful context beyond 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?
Three short front-loaded sentences with no filler; the core capability leads and access constraints follow. The RIS/RI/HRI acronym switching introduces mild noise, keeping it short of ideal.
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 one-parameter read tool with no output schema, the description covers what is returned (current RI plus citation URL) and the tiering needed to get HRI. Nothing critical is missing, though the acronym inconsistency between RIS and RI could confuse an agent mapping it to get_subject_ri.
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 'symbol' parameter is already documented with accepted formats ('Fe', 'Iron', '26'). The description only hints at granularity via '118 chemical elements' and adds no format or validation detail beyond the schema, so 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 ('Get current Research Intensity (RIS) ... for one of the 118 chemical elements') with a clear element-scoped boundary that separates it from the sibling get_subject_ri. It does not explicitly name that sibling as the contrast, so an agent must infer the element-vs-subject split from the scope wording 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?
Usage is implied by the single-purpose element lookup, and there is one concrete precondition ('No API key needed', HRI requires Personal+). However, it never says when to prefer this over get_subject_ri or how it pairs with get_element_papers, so an agent must infer the routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full yearly (or monthly) RIS/HRI history for one topic/keyword/sector. Requires a Personal+ account. Without a key, pay per call: $0.10 in USDC on Base or Solana via x402 (send the payment in _meta["x402/payment"]).
| Name | Required | Description | Default |
|---|---|---|---|
| resolution | No | yearly | |
| subject_id | Yes | ||
| subject_type | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It does disclose substantial behavior: account tier requirement, per-call pricing ($0.10 USDC on Base/Solana), and the exact x402 payment mechanism in _meta["x402/payment"]. It says nothing about rate limits, pagination, or data freshness/coverage of the returned history.
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 tight sentences, front-loaded with what is returned, then the access/payment conditions. No filler; the only minor cost is the jargon 'RIS/HRI' being used before it is defined.
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 no output schema and no annotations, the description should cover the return shape and parameter meanings. It conveys the data domain, granularity, and access model, but leaves the two required parameters and the return structure undocumented, which is a meaningful gap for a 3-parameter 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?
Schema description coverage is 0%, so the description must compensate. It does explain resolution (yearly/monthly) and loosely frames subject_type as topic/keyword/sector, but the enum only allows keyword/sector, so the description's 'topic' introduces ambiguity rather than clarifying. subject_id semantics remain undocumented.
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: returns full yearly or monthly RIS/HRI history for a single subject. It implies scope (one subject) but does not name or contrast with the closely related siblings get_subject_ri, get_subject_papers, or get_element_ri, so an agent must infer which of these returns which dataset.
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 gives a real prerequisite (Personal+ account, or pay-per-call without a key), which is useful when-to-use context. However it offers no guidance on when to pick this over get_subject_ri or get_subject_papers, and no exclusions, so the routing decision is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The top papers for one research topic (resolve it with search_subjects first) -- title, DOI, venue, year, citations. Use it when asked what to READ about a specific topic, rather than how active it is. sort=impact (default) favours recent, well-cited work; sort=foundational gives the most-cited classics; sort=newest the latest. Each paper carries its abstract where one is on file (about 6 in 10). Requires a Personal+ account. Capped at 100 papers with no pagination. Without a key, pay per call: $0.02 for up to 20 papers, $0.10 for up to 100, in USDC on Base or Solana via x402 (send the payment in _meta["x402/payment"]).
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | impact = citation-impact ranking (default); newest = most recently published first; foundational = most-cited first (the classics a reading list starts from). | impact |
| limit | No | ||
| subject_id | Yes | ||
| subject_type | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and delivers: Personal+ account requirement, a hard 100-paper cap with no pagination, ~60% abstract coverage, and a detailed pay-per-call pricing model including the x402 payment field. This is unusually rich operational context.
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 purpose and routing before behavior and pricing, and nearly every sentence earns its place. The pricing sentence is long and dense but delivers information an agent needs before calling.
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?
No output schema exists, so the description usefully lists return fields and abstract coverage, plus auth and cost. The main residual gap is the unresolved semantics of subject_type/subject_id, which are neither described here nor in the 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?
Schema coverage is only 25%, so the description must compensate. It explains the sort modes well (though the schema already documents sort) and mentions the 100 cap implied by limit, but says nothing about what subject_type values ('keyword' vs 'sector') mean or the subject_id format, leaving half the parameters semantically thin.
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 ('the top papers for one research topic') and enumerates the returned fields (title, DOI, venue, year, citations), which separates it from the sibling ranking tools get_subject_ri and get_subject_history.
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 usage: 'Use it when asked what to READ about a specific topic, rather than how active it is,' contrasting with the activity-oriented siblings. It also names the prerequisite (resolve the topic with search_subjects first) and explains when to pick each sort mode.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get RI, RIS, HRI and paper count for one research topic/keyword/sector. Requires a Personal+ account -- call search_subjects first to resolve subject_type/subject_id. Without a key, pay per call: $0.01 in USDC on Base or Solana via x402 (send the payment in _meta["x402/payment"]).
| Name | Required | Description | Default |
|---|---|---|---|
| subject_id | Yes | ||
| subject_type | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it discloses meaningful operational context: a Personal+ account requirement and a pay-per-call fallback ($0.01 USDC on Base or Solana via x402, with the payment placed in _meta['x402/payment']). It does not mention pagination, rate limits, or error behavior, but the auth/payment disclosure is substantive.
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 dense sentences with zero filler: return values first, then prerequisite, then auth/payment. Every sentence earns its place and the payload 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?
For a 2-param read tool with no output schema, the description covers what is returned, how to resolve inputs, the account tier, and the payment path. It is nearly complete; only the meaning of the domain abbreviations (RI/RIS/HRI) and ID format are unstated.
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 0%, so the description must compensate: it clarifies that subject_id/subject_type derive from search_subjects and that the subject is a research topic/keyword/sector, which loosely maps to the enum. It still doesn't state the expected ID format or the distinction between 'keyword' and 'sector' beyond naming them, leaving a real gap.
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 ('Get') and enumerates the exact metrics returned (RI, RIS, HRI, paper count) for a research topic/keyword/sector. This is far more specific than the title/name alone, though it doesn't explicitly contrast itself with siblings like get_element_ri or get_subject_papers.
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 prerequisite chain: 'call search_subjects first to resolve subject_type/subject_id', naming the sibling to use and why. It also flags the account/payment conditions. It stops short of saying when to prefer this over get_subject_papers or get_subject_history, which share the same subject vocabulary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scope a multi-term question with a boolean filter: +must -exclude "exact topic" (a OR b) wild* year:2015..2026, over element symbols or names and EXACT topic names (e.g. +Li +Co "solid electrolyte" -sulfide). Words that are neither are DROPPED, and wildcards can expand into unrelated fields: read warnings first -- it lists every dropped term with the nearest topics, every abbreviation read as a topic, and every wildcard expansion. Returns how many papers match, by year and by research community, the nearest broader query when nothing matches, and a quote_id that lab_run turns into the ranked papers. Narrow filters (two elements + one topic) work best. Requires a Professional+ account. Without a key, pay per call: $0.01 in USDC on Base or Solana via x402 (send the payment in _meta["x402/payment"]).
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | The filter, in the syntax above. | |
| markdown | No | Alternative: markdown carrying the filter in a ```query fenced block. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full load and does so richly: dropped non-element/non-topic words, wildcard expansion into unrelated fields, reading `warnings` for dropped terms/abbreviations/expansions, account requirements (Professional+), and pay-per-call pricing with exact rails (_meta x402, $0.01 USDC on Base/Solana). This goes well beyond what the schema reveals.
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?
It is front-loaded with the syntax, which is good, but it is dense and packs syntax, warnings behavior, return shape, best-practice sizing, account tier, and payment rails into one long paragraph. The syntax example is valuable but the whole is crowded.
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 no output schema, the description does describe returns (match counts by year and community, nearest broader query on no match, quote_id). Combined with the warnings guidance and pricing/account requirements, an agent has enough to call it correctly, though the syntax could use a tighter spec.
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 two parameters (query, markdown) are already documented. The description explains the query syntax and the markdown-alternative use of a fenced block, but since the schema fully documents both, this is baseline territory.
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 this is a query-scoping/counting tool via a specific boolean filter syntax over element symbols and topic names. It distinguishes itself from get_element_papers/search_subjects by being a scoping step that produces a quote_id for lab_run. The verb 'scope' is a bit abstract but the resource and output are concrete.
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 gives explicit usage direction: narrow filters (two elements + one topic) work best, read `warnings` first, and mentions the lab_run handoff that turns a quote_id into ranked papers. It doesn't explicitly contrast against the get_* siblings, but the scoping-to-lab_run flow makes its role clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the papers for a lab_quote: pass its quote_id and a depth (papers_20 or papers_100) to get the top papers matching the quoted filter, ranked by impact, with the curation behind each rank. Each paper carries its abstract where one is on file (about 6 in 10). A stale or expired quote is refused. Requires a Professional+ account. Without a key, pay per call: the quoted price of the depth, less the $0.01 quote credit in USDC on Base or Solana via x402 (send the payment in _meta["x402/payment"]).
| Name | Required | Description | Default |
|---|---|---|---|
| depth | No | papers_20 | |
| quote_id | Yes | From lab_quote. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so well: it discloses auth requirements (Professional+), pay-per-call pricing (depth price less the $0.01 credit), payment channel (USDC on Base/Solana via x402, sent in _meta['x402/payment']), ranking behavior (by impact with curation behind each rank), and an error condition (stale/expired quote refused). This is unusually rich behavioral context.
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?
Purpose and the required quote_id are front-loaded, and the pricing/auth details follow. It's dense but each sentence adds actionable information; the payment mechanics sentence is longer than strictly necessary but still 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 no output schema, the description usefully covers return content (abstracts present in ~6 in 10 papers, curation behind each rank). It also covers auth, cost, and error behavior. It could say more about the shape of the 'curation' data or pagination, but it's substantially complete for a 2-param 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?
Schema coverage is 50% (quote_id documented, depth only enum-typed). The description explains quote_id's origin ('from lab_quote') and adds meaning for depth by describing both enum values and what they return (top papers matching the quoted filter, ranked by impact). It compensates well for the undocumented depth parameter.
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 gives a specific verb (get) and resource (papers for a lab_quote) and immediately names the upstream sibling it depends on (lab_quote). It's clear this is a quote-fulfillment retrieval tool, distinguishable from get_subject_papers/get_element_papers, though the tool name 'lab_run' is slightly misleading since nothing is 'run'.
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 states the flow (pass the quote_id from lab_quote) and the selecting condition for depth, plus an exclusion (a stale or expired quote is refused). It does not explicitly contrast with the other paper-retrieval siblings, so it stops short of a full when/when-not comparison.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
CALL THIS FIRST for a literature question about chemistry, materials or physics research -- a broad one ('what matters in X') or a specific process or parameter one (a deposition condition, a property value, a defect mechanism). Send the question in plain words (q), or a paper you already know (paper: DOI or title). Returns reading lists in four lenses: relevant (the papers whose TITLE AND ABSTRACT best match the question, across the whole corpus, BM25 -- start here for a specific question), foundational (the classics the question's own papers cite most), now (highest impact, young papers' citations projected) and newest (last two years); plus the research communities and element sub-communities the question is about, with why each matched and whether it is rising. Put the question's key terms in q: filler words are ignored. unmatched_terms lists words that matched nothing; rephrase those. Each paper carries its DOI, a one-line reason and its abstract where one is on file. Our corpus is curated, not complete: the relevant lens also brings up to 3 of every 10 results from OpenAlex, marked source='openalex' and labelled not yet curated. One page = up to 10 papers per lens; ask for page 2+ only if needed. Requires a Personal+ account. Without a key, pay per call: $0.05 in USDC on Base or Solana via x402 (send the payment in _meta["x402/payment"]).
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | The research question, in plain words. | |
| page | No | ||
| paper | No | Alternative to q: a DOI or title to start from. | |
| lenses | No | Default: all four. | |
| page_size | No | Papers per lens. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so richly: it discloses the four lens algorithms (BM25 title/abstract match, citation classics, projected young-paper impact, last-two-years), curated-vs-OpenAlex corpus limits (up to 3 of every 10 results unmarked, source='openalex'), and auth/cost model (Personal+ required, $0.05 USDC via x402 in _meta). This is exactly the behavioral context an agent needs for a mutation-free read tool with no 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 priority instruction is front-loaded and most sentences are dense with substance (lens definitions, corpus caveats, payment). It is long and mixes return-value description, pricing and auth into one block, which slightly dilutes scanability, but there is little 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?
There is no output schema, so the description must explain results and it does: lens composition, why/previous-citation info, per-paper DOI plus reason plus abstract, source='openalex' markers, and page size. Combined with the covered auth/cost and pagination details, an agent has everything needed to call and interpret it.
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 80%, so the baseline is 3, and the description adds real value on top: it explains that q should carry key terms because 'filler words are ignored,' that paper is a DOI-or-title alternative to q, and what each lens enum means. It does not add much on page/page_size beyond the schema defaults, keeping it just under a 5.
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?
Opens with a specific imperative verb and resource: 'CALL THIS FIRST for a literature question about chemistry, materials or physics research.' It explicitly scopes the domain and contrasts with siblings like get_element_papers/get_subject_papers by centering on free-text literature questions rather than element/subject lookups. An agent can route without inspecting other schemas.
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?
States clear triggering conditions ('broad one' or 'specific process or parameter one') and prioritizes itself with 'CALL THIS FIRST.' It also guides pagination ('ask for page 2+ only if needed') and lens selection. It never explicitly names a sibling to prefer instead nor states when NOT to use it, so it falls short of 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolve a free-text query (a compound, material, or research topic) to its subject_type/subject_id for use with get_subject_ri. Free with any API key. Without a key, pay per call: $0.01 in USDC on Base or Solana via x402 (send the payment in _meta["x402/payment"]).
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden and does so well: it discloses the cost model (free with any API key, otherwise $0.01 per call in USDC), the chains supported (Base, Solana), and the x402 payment mechanism in _meta. It does not detail rate limits or the exact return shape beyond the two resolved 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?
Two front-loaded sentences: the purpose and downstream use come first, followed by the pricing/auth detail. The x402 payment instructions are verbose but earn their place given no annotations exist to convey auth requirements.
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 resolver with no output schema and no annotations, the description covers purpose, downstream usage, and the full payment/auth path. It is nearly complete; only a note on what happens with ambiguous or unmatched queries is absent.
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 0% for the single 'query' parameter, but the description compensates by explaining what a query may contain (a compound, material, or research topic) and what it resolves to. It adds meaning the bare string schema lacks, though it gives no format examples or edge-case handling.
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 gives a specific verb+resource ('resolve a free-text query... to its subject_type/subject_id') and clarifies the input domain (compound, material, or research topic). It also names the downstream sibling it feeds (get_subject_ri), which distinguishes it from the get_* tools that require an existing ID.
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 clearly positions the tool as a pre-step before get_subject_ri, so the agent knows the workflow context. It does not explicitly state when NOT to use it (e.g., when an ID is already known), but the routing intent is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
get_element_papers1 field changedInput schema / properties / symbol / descriptionPrevious value: -"Element symbol, e.g. 'Fe'"New value: +"Element symbol, e.g. 'Fe' (a name like 'Iron' or an atomic number like '26' also works)"get_element_ri1 field changedInput schema / properties / symbol / descriptionPrevious value: -"Element symbol, e.g. 'Fe'"New value: +"Element symbol, e.g. 'Fe' (a name like 'Iron' or an atomic number like '26' also works)"research2 fields changedInput schema / properties / lenses / descriptionPrevious value: -"Default: all three."New value: +"Default: all four."Input schema / properties / lenses / items / enumPrevious value: -[
- "foundational",
- "now",
- "newest"
-]New value: +[
+ "relevant",
+ "foundational",
+ "now",
+ "newest"
+]researchget_element_papers2 fields changedInput schema / properties / sort / descriptionPrevious value: -"impact = citation-impact ranking (default); newest = most recently published first."New value: +"impact = citation-impact ranking (default); newest = most recently published first; foundational = most-cited first (the classics a reading list starts from)."Input schema / properties / sort / enumPrevious value: -[
- "impact",
- "newest"
-]New value: +[
+ "impact",
+ "newest",
+ "foundational"
+]get_subject_papers2 fields changedInput schema / properties / sort / descriptionPrevious value: -"impact = citation-impact ranking (default); newest = most recently published first."New value: +"impact = citation-impact ranking (default); newest = most recently published first; foundational = most-cited first (the classics a reading list starts from)."Input schema / properties / sort / enumPrevious value: -[
- "impact",
- "newest"
-]New value: +[
+ "impact",
+ "newest",
+ "foundational"
+]lab_runlab_quoteget_element_papersget_element_riget_subject_historyget_subject_papersget_subject_risearch_subjectsPay-per-call x402 arXiv paper search, metadata, abstracts, and category listings.
Scrape arXiv, OpenAlex and Crossref papers by author, topic, journal or DOI. Pay per row.
Rank CS/AI/ML papers by citations, forecast impact, or code adoption; trace 23.2M citation edges.
Search 250M+ research papers, citations and author profiles. Free OpenAlex account; OAuth sign-in.
Add one secure layer between your agents and this server.