Skip to main content
Glama

Aevia

by ai.aeviamodeler
OverviewDiscussionsAdmin

Get literature excerpts

knowledge_get_excerpts
Read-onlyIdempotent

Search the library and return abstracts with matching passages. Three modes: (1) query only → discover documents AND return each one's abstract + relevant chunk excerpts in one call; (2) document_refs only → abstract + first chunks per doc as a table-of-contents glimpse; (3) both → re-rank chunks against the query, scoped to those refs. At least one of query or document_refs is required. In query-discovery mode you may also scope by journal / year_from / year_to (ignored when document_refs is given).

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
limitNoMax documents (only applies when document_refs is omitted, default: 10).
queryNoSearch text. Required when no documents are selected (discovery mode) — finds matching documents. Optional once document_refs are given: include it to rank those documents' chunks by relevance, or omit it to pull each document's abstract + opening chunks. The library is English-language: technical terms and scientific names match best.
journalNoOptional. Restrict the search to ONE journal, by its full name (e.g. "Journal of Cleaner Production"). A distinctive fragment also works ("Cleaner Production"), but a fragment matching several journals is rejected with the candidates listed — never guessed at — so prefer the full name. To compare journals, run one search per journal. Omit to search every document this session can reach — including the user's own uploads and anything else with no journal recorded, which a journal filter would exclude.
year_toNoOptional inclusive upper bound on publication year. Omit for no upper bound.
year_fromNoOptional inclusive lower bound on publication year (e.g. 2020 for "recent"). Omit for no lower bound.
document_refsNoSpecific documents to pull from, as knowledge refs from a recent knowledge_search (e.g. ["k1", "k7"]). Provide these to fetch those exact documents (abstract + chunks) instead of discovering by query — the metadata filters (Scope / years) then no longer apply. Required if query is omitted.
top_k_chunks_per_docNoMax chunks to return per document (default: 3).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • changedInput schema / properties / limit / type
      Previous value: -"number"New value: +"integer"
    • changedInput schema / properties / top_k_chunks_per_doc / type
      Previous value: -"number"New value: +"integer"
  2. Changed1 schema field changed
    • changedInput schema / properties / query / description
      Previous value: -"Search text. Required when no documents are selected (discovery mode) — finds matching documents. Optional once document_refs are given: include it to rank those documents' chunks by relevance, or omit it to pull each document's abstract + opening chunks."New value: +"Search text. Required when no documents are selected (discovery mode) — finds matching documents. Optional once document_refs are given: include it to rank those documents' chunks by relevance, or omit it to pull each document's abstract + opening chunks. The library is English-language: technical terms and scientific names match best."
  3. Changed6 schema fields changed
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • removedInput schema / additionalProperties
      Removed value: -false
    • addedInput schema / properties / year_from / maximum
      Added value: +9007199254740991
    • addedInput schema / properties / year_from / minimum
      Added value: +-9007199254740991
    • addedInput schema / properties / year_to / maximum
      Added value: +9007199254740991
    • addedInput schema / properties / year_to / minimum
      Added value: +-9007199254740991
  4. First observed

TDQS

A4.1/5.0
Behavior4/5

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so safety is covered. The description adds genuinely useful behavior beyond that: the library is English-language so technical terms/scientific names match best, a multi-journal fragment is rejected with candidates rather than guessed, omitting journal widens scope to uploads and journal-less documents, and filters are inert in document_refs mode. Return shape (abstract + chunks) is also sketched.

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

Conciseness5/5

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

Front-loaded with the core action, then a tight numbered enumeration of the three modes, then the input requirement and the filter-scoping caveat. Every sentence earns its place and the parenthetical constraints are load-bearing rather than filler.

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?

With 7 parameters, no required params, and no output schema, the description does the important work of explaining mode interactions and mutual constraints, which is what an agent needs to call it correctly. It could say a bit more about what a returned excerpt/chunk actually contains (ordering, sizing) and about behavior when a ref is invalid, but the essentials are present.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic value beyond the schema: the trade-off of omitting journal (includes the user's own uploads), the fragment-resolution/rejection behavior, and the interaction where scope filters are ignored once document_refs are given. It does not add anything for limit/top_k_chunks_per_doc or the year bounds, which the schema already handles.

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

Purpose4/5

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

The description states a concrete verb+resource ('Search the library and return abstracts with matching passages') and enumerates three operating modes keyed on which inputs are supplied. It is very clear about what the tool produces, but it never names sibling tools (knowledge_search, knowledge_get_full_document), so differentiation from them is only implied by the 'discover AND return excerpts in one call' framing.

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

Usage Guidelines4/5

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

Strong mode-selection guidance: query-only for discovery+excerpts, document_refs-only for a table-of-contents glimpse, both for re-ranking scoped to refs, plus the hard constraint that at least one of query/document_refs is required. It also states when metadata filters are ignored. It stops short of naming an alternative tool for pure document discovery (e.g. knowledge_search), which would be the 5-level signal.

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

All Aevia toolsInspect
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