Agent Tools

papers_search

Free tier: 25 calls/day per IP with header X-Free-Call: 1 (or ?free=1), then pay per call. Scholarly paper search for research agents: keywords or a DOI in, matching papers out with title, authors, year, venue, DOI, citation count, open access PDF or page link, retraction flag and abstract. Filter by year range and open access, sort by relevance, citations or newest. Source OpenAlex, Crossref fallback. Price $0.006 USDC per call via x402. Example output: {"total_matches":136358,"returned":1,"papers":[{"title":"Example paper on retrieval augmented generation","authors":["A. Author","B. Author"],"authors_total":2,"year":2024,"venue":"Example Journal","doi":"10.1234/example.5678","doi_url":"https://doi.org/10.1234/example.5678","citations":181,"open_ac

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "q": "<q>"
    },
    "name": "papers_search"
  }
}

Input Schema

Name	Required	Description
`q`	Yes	Search words, or a DOI such as 10.1038/nature14539
`free`	No	Use the shared free allowance (25 successful calls per IP per UTC day across eligible tools). Defaults to false.
`sort`	No
`limit`	No	1 to 25, default 10
`to_year`	No	Optional latest year
`from_year`	No	Optional earliest year, e.g. 2020
`open_access`	No	true to keep only open access papers

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedNov 5, 2026

addedInput schema / properties / free

Added value: +{
+  "description": "Use the shared free allowance (25 successful calls per IP per UTC day across eligible tools). Defaults to false.",
+  "type": "boolean"
+}

AddedOct 30, 2026

TDQS

A3.9/5.0

Behavior4/5

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

With no annotations, the description carries the full burden and does well: it discloses the 25-call/IP/day free allowance and the header or query-param mechanism, the $0.006 USDC x402 payment, and the upstream source plus fallback. Gaps remain around what happens when the free quota is exhausted, whether abstracts are truncated, and the handling of the retraction flag, but the cost/auth behavior an agent most needs is present.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Dense but purposeful: pricing/access rules first, then purpose, then output shape, with an inline example. The example JSON is cut off mid-token ('open_ac'), which is a sloppiness that costs it a point, and the billing sentence competes with the purpose sentence for the front-loaded position.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, and the description compensates by listing every returned field and including a concrete sample response, so an agent knows what comes back. It covers inputs, cost, and provenance for a 7-parameter tool; only pagination behavior (total_matches vs. returned/limit) and failure modes are left unexplained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

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

Schema description coverage is 86%, so the baseline is 3. The description restates the year-range, open-access and sort semantics already documented in the schema, and its one genuine addition is mapping the `free` parameter to the X-Free-Call header / ?free=1 form. It adds no interpretation for `limit` bounds or the string-typed boolean/year fields that could trip an agent up.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource ('Scholarly paper search'), specifies the accepted inputs ('keywords or a DOI in'), and enumerates the returned fields (title, authors, year, venue, DOI, citations, OA link, retraction flag, abstract). Corpus ('OpenAlex, Crossref fallback') further pins down the domain, making it trivially distinguishable from domain-adjacent siblings like clinical_trials_search or federal_register_search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

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

Usage context is implied ('for research agents') and the free-tier versus paid path is explained clearly, including how the `free` flag or header selects it. However, there is no explicit when-to-use/when-not guidance and no alternative tool is named — the agent must infer on its own that clinical_trials_search or sec_filings cover other literature domains.

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

All Agent Tools tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?