Research intensity for 118 elements and topics, ~10M papers. Free element scores; x402 pay-per-call.
Scored across 9 tools
The element- vs subject-scoped pairs (get_element_ri / get_subject_ri, get_element_papers / get_subject_papers) are mostly separable, and lab_quote→lab_run is a clean two-step pair. But three tools (research, get_subject_papers, lab_run) all return ranked paper lists with overlapping semantics, so an agent must lean heavily on prose hints like 'rather than how active it is' to choose correctly.
Predominantly a consistent snake_case verb_noun pattern (get_element_papers, get_subject_ri, search_subjects), with the lab_* pair being a readable namespaced variant. The bare verb 'research' breaks the pattern slightly but is unambiguous.
Nine tools is well within a comfortable range and each surfaces a distinct capability (resolve, current RI, history, papers, boolean scoping, ranked retrieval). No filler tools and no obvious bundling of unrelated functions.
The surface covers discovery, metric retrieval (RI/RIS/HRI), and literature search with both topic-scoped and boolean-filtered paths, forming a coherent workflow. Minor gaps exist: no direct element-level history/trend tool, no cross-element or multi-subject comparison, and no way to browse sectors/subjects without a free-text query.
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?
Beyond the read-only/idempotent annotations, it discloses substantial operational facts: Personal+ account requirement, a hard 100-paper cap with no pagination, abstract coverage of roughly 60%, and full pay-per-call pricing tiers with the x402 payment field. This is exactly the kind of context annotations cannot carry.
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 and example, then ranking behavior, then access/pricing constraints — a sensible ordering with little waste. The x402 payment sentence is long but carries information an agent cannot get elsewhere.
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 the returned fields (title, DOI, venue, year, citations) and abstract availability, and it covers auth, caps, and payment. An agent has everything needed to call it and understand the response shape.
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 the critical non-obvious constraint that keyword must name one of the element's topics exactly (case aside) plus the 100-item ceiling on limit. The sort explanation partly duplicates the enum's own schema description, keeping it from 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?
States a specific verb+resource: 'The top papers for one element,' with the keyword narrowing scope spelled out and a concrete example (symbol='Al', keyword='aluminum nitride'). It does not explicitly distinguish itself from the close sibling get_subject_papers, so an agent must infer the element-vs-subject split.
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 clear usage context: keyword is optional and must exactly match one of the element's topic names, and it names search_subjects as the way to discover those names. It also explains which sort mode to pick (impact default, foundational for classics, newest for recency). No explicit when-not or contrast with get_subject_papers/get_element_ri.
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?
Annotations already declare read-only, idempotent, non-destructive behavior, so the bar is lower; the description still adds real value by disclosing that no API key is needed, that a citation URL is returned, and that historical HRI requires a Personal+ key. It does not cover error behavior for unknown symbols, which is a minor remaining gap.
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 sentences with no filler, and the core purpose is front-loaded before the access-condition details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read tool with no output schema, the description covers the return values (RIS plus citation URL, HRI under paid tier) and access requirements. Only failure modes for invalid symbols are 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 coverage is 100% and the schema already documents that symbols, names, and atomic numbers are accepted, so the description adds nothing parameter-specific. Baseline 3 applies when the schema carries all parameter 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 ('Get current Research Intensity (RIS)') and bounds the domain to 'one of the 118 chemical elements', which separates it from the subject-oriented sibling get_subject_ri. It never names the sibling explicitly, so differentiation requires inference.
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 implies an element-symbol lookup and notes key requirements, but gives no explicit when-to-use versus get_element_papers or get_subject_ri, and no exclusion conditions. Usage is inferable rather than stated.
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?
Annotations already declare readOnlyHint/idempotentHint, so the description's real contribution is the auth tier ('Requires a Personal+ account') and the payment protocol details (USDC on Base or Solana via x402, _meta["x402/payment"]), which are valuable and non-obvious. It doesn't disclose response size or pagination expectations for a full-history payload.
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: capability, account requirement, payment fallback with exact mechanism. Front-loaded with the core purpose 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?
No output schema exists, so the description would ideally say what 'RIS/HRI history' returns structurally (per-year values, formatting). It covers access/payment completely but leaves the returned data shape implicit for a full-history read.
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 the resolution choices (yearly/monthly) and that subject_type is keyword/sector, but subject_id is never explained (ID format, where to obtain it) despite being required.
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 (yearly/monthly RIS/HRI history) and scope (one topic/keyword/sector), which is more precise than the title alone. It doesn't explicitly differentiate itself from siblings like get_subject_ri or get_subject_papers, but the 'history' framing is a distinguishable verb+resource.
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 access conditions (Personal+ account required, or pay-per-call via x402) but never says when to choose this over get_subject_ri/get_subject_papers or when yearly vs monthly is appropriate. Usage is implied rather than guided.
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?
Goes well beyond the readOnly/idempotent annotations: discloses the 100-paper cap with no pagination, the 6-in-10 abstract coverage, the Personal+ account requirement, and the x402 pay-per-call price tiers with the exact _meta key. Only minor gap is not saying what an empty result or missing abstractions look like in the response.
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 usage, then pricing and quotas. Every sentence carries information, though the payment-scheme details make the tail dense and slightly harder 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 usefully enumerates return fields and documents access, cost and result caps. Nearly complete; the unexplained subject_type enum is the only substantive omission for a 4-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 only 25%, and the description compensates for limit (cap of 100) and subject_id (must be resolved via search_subjects) plus elaborates sort semantics. However, it never explains the subject_type enum values keyword vs sector, which is the most ambiguous required 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?
States a specific verb and resource ('top papers for one research topic') and enumerates the returned fields (title, DOI, venue, year, citations). It also distinguishes itself from sibling get_subject_ri by framing the choice as 'what to READ about a specific topic, rather than how active it is.'
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 says to resolve the topic with search_subjects first, and gives a clear when-to-use rule contrasted against the activity-oriented sibling. The sort options are also each tied to an intent (recent well-cited, classics, latest).
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?
The annotations already declare this as a read-only, idempotent, non-destructive, closed-world operation. The description adds useful behavioral context beyond annotations: the Personal+ requirement and the $0.01 USDC payment flow on Base or Solana through _meta["x402/payment"].
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 tight sentences with no wasted text. Purpose, prerequisite, account requirement, and payment fallback are front-loaded in a useful order.
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 two-parameter read-only lookup with no output schema, it covers purpose, authentication, prerequisite resolution, and payment behavior well. It still leaves some ambiguity around parameter formats and the exact return structure, but the core invocation context is present.
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 has to carry parameter meaning. It names subject_type and subject_id and says to resolve them with search_subjects, but it does not explain the expected ID format or clarify the enum values beyond the keyword/sector wording.
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: get RI, RIS, HRI, and paper count for one research topic/keyword/sector. It is clear what the tool returns, but it does not explicitly distinguish this subject-level tool from siblings such as 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?
It gives a clear prerequisite: call search_subjects first to resolve subject_type and subject_id. It also explains the Personal+ account requirement and the pay-per-call fallback via x402, though it does not explicitly say when to choose this tool over sibling research-intensity tools.
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?
Annotations already cover read-only, idempotent, non-destructive behavior, but the description adds substantial context: dropped terms, wildcard expansions, warnings content, return summaries by year/community, nearest broader query, quote_id handoff, and account/payment requirements.
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 dense but front-loaded with purpose and syntax, and every clause carries information. It could be more structured for readability, but there is no significant 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 no output schema and only two parameters, the description fully explains the return values, warnings payload, quote_id handoff to lab_run, and account/payment prerequisites. An agent has enough to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3, but the description adds valuable query syntax and examples beyond what the schema provides. The markdown alternative parameter is left to the schema, keeping this below 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?
States a specific verb, resource, and scope: 'Scope a multi-term question with a boolean filter' over element symbols/names and exact topic names. The syntax and the lab_run handoff make it clearly distinguishable from execution 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?
Gives practical guidance: read `warnings` first, narrow filters (two elements + one topic) work best, and lab_run turns quote_id into ranked papers. It lacks an explicit when-not-use comparison against research/search_subjects, but the intended workflow is 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?
Adds substantial behavior beyond the annotations: abstract availability (~6 in 10), refusal of stale/expired quotes, Professional+ account requirement, and the full x402 payment mechanics including currency, chains, the $0.01 quote credit, and the _meta["x402/payment"] field. This is exactly the kind of auth/pricing/failure-mode context annotations cannot carry.
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 inputs in the first sentence, then layers return details, failure modes, and billing. Dense but every clause carries information; the payment sentence is long but the pricing detail is load-bearing for a pay-per-call tool.
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 still characterizes the return: papers with abstracts and the curation/ranking rationale. Combined with the auth, billing, and failure conditions, an agent has everything needed to decide and 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 50% — quote_id is documented ('From lab_quote') but depth is only an enum with a default. The description compensates by naming both depth values and explaining what they control (top papers by impact matched to the quoted filter). It does not state the effective upper bound or ordering differences between papers_20 and papers_100 beyond the labels.
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 the papers for a lab_quote') plus the exact inputs (quote_id, depth) and the output semantics (top papers matching the quoted filter, ranked by impact, with curation behind each rank). This clearly separates it from lab_quote (which issues quotes) and the get_subject_papers / get_element_papers 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?
Explains the prerequisite workflow (quote_id comes from lab_quote), the depth choice, and a clear when-not condition: a stale or expired quote is refused. Also gives the account requirement and a pay-per-call fallback path. It stops short of explicitly contrasting with the other paper-retrieval siblings, so a 4 rather than 5.
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?
Annotations already cover read-only/idempotent/open-world, but the description adds substantial context the annotations cannot: the corpus is curated but incomplete, the relevant lens blends up to 3 of every 10 results from OpenAlex marked source='openalex' and labelled not-yet-curated, and the access model (Personal+ account, or $0.05 USDC per call via x402 with payment in _meta['x402/payment']).
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 imperative 'CALL THIS FIRST' and the question types, and nearly every clause carries operational information (lens behavior, corpus limits, payment). It is a single very dense paragraph, though, and the lens definitions plus payment mechanics make it heavier than ideal for skimming.
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, yet the description fully covers return shape: papers with DOI, one-line reason and abstract, four lenses with their semantics, matched communities with rising/falling status, unmatched_terms, source labeling for OpenAlex results, and page/per-lens limits. Nothing an agent needs to call or interpret 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 80%, so the baseline is 3, but the description adds real meaning: q ignores filler words and unmatched terms are surfaced for rephrasing, paper accepts a DOI or title as an alternative to q, each lens is defined (BM25 title/abstract match, foundational citations, projected impact, last two years), and page_size maps to 'up to 10 papers per lens'. The page parameter itself is left only to schema bounds.
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 action (returns reading lists) for a specific domain (chemistry, materials, physics literature questions) and enumerates what comes back: four lenses plus communities. It clearly differs from the sibling lookup tools (get_subject_papers, get_element_papers, get_subject_history), which are entity-scoped rather than question-driven.
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 says 'CALL THIS FIRST', distinguishes broad questions ('what matters in X') from specific process/parameter questions, names the alternative input path (q vs paper: DOI or title), and gives a reasoning hint on lens order ('start here for a specific question' on relevant) and pagination ('ask for page 2+ only if needed').
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?
Annotations already cover the read-only/idempotent/closed-world profile, and the description adds genuinely new behavioral context: it is free with any API key and otherwise costs $0.01 via x402 with payment sent in _meta["x402/payment"]. This is high-value cost/auth disclosure that annotations cannot convey, though nothing is said about result cardinality or no-match 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 tight sentences with the purpose and workflow role front-loaded, then pricing. No filler or restatement of the 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?
For a one-parameter tool with no output schema, the description covers purpose, return fields, downstream use, and cost. Minor gaps remain around multiple matches and empty results, which matter for an agent deciding whether to trust the resolution.
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 carries the burden, and it does explain that 'query' is free text naming a compound, material, or research topic. It also clarifies the return shape (subject_type/subject_id). It adds no format or length constraints, so slightly short of full compensation.
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 ('resolve') and resource (free-text query -> subject_type/subject_id), and names the downstream sibling get_subject_ri, so an agent can tell exactly what this returns and where it fits in the workflow.
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 positions the tool as a prerequisite for get_subject_ri, which is clear usage context. It does not mention alternatives (e.g., when to use get_element_ri instead) or what to do when a query yields no match, so it stops short of full when/when-not guidance.
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.
Topic popularity, interest over time and trending topics from Wikipedia pageviews (x402 paid).
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.
Add one secure layer between your agents and this server.