Skip to main content
Glama

Publication facets

list_publication_facets
Read-onlyIdempotent

Ranked facets for the entire filtered bibliography before pagination. Uses the same selection rules as search_publications.

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": {
      "facet": "<facet>"
    },
    "name": "list_publication_facets"
  }
}

Input Schema

NameRequiredDescriptionDefault
typeNoExact type; discover values with list_publication_facets
facetYes
limitNoDefault 25, max 100
venueNoJournal/book title, partial
authorNoAuthor/editor name, either name order
offsetNo
keywordNoTitle, abstracts, venue, subjects or full text; every word must match, quote a phrase
subjectNoSubject heading, partial
year_toNo
languageNoLanguage name or ISO code
year_fromNo
added_sinceNoAdded to AMIRA on or after this ISO date
has_fulltextNoFilter by extracted full-text availability

Output Schema

NameRequiredDescriptionDefault
countYes
facetYes
offsetYes
filtersNo
resultsYes
has_moreYes
next_offsetNo
total_matchesYes
missing_valuesYes
effective_limitNo
requested_limitNo
response_limitedNo
total_publicationsYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changed
    • removedInput schema / $schema
      Removed value: -"https://json-schema.org/draft/2020-12/schema"
    • removedOutput schema / $schema
      Removed value: -"https://json-schema.org/draft/2020-12/schema"
    • removedOutput schema / additionalProperties
      Removed value: -false
    • removedOutput schema / properties / filters / propertyNames
      Removed value: -{
      -  "type": "string"
      -}
    • removedOutput schema / properties / results / items / additionalProperties
      Removed value: -false
  2. Changed1 schema field changed
    • removedInput schema / properties / limit / maximum
      Removed value: -9007199254740991
  3. Changed9 schema fields changed
    • addedInput schema / properties / added_since
      Added value: +{
      +  "description": "Added to AMIRA on or after this ISO date",
      +  "maxLength": 40,
      +  "type": "string"
      +}
    • addedInput schema / properties / author / maxLength
      Added value: +1000
    • changedInput schema / properties / keyword / description
      Previous value: -"Title, abstract, venue, subjects or full text; substring match"New value: +"Title, abstracts, venue, subjects or full text; every word must match, quote a phrase"
    • addedInput schema / properties / keyword / maxLength
      Added value: +1000
    • addedInput schema / properties / language / maxLength
      Added value: +1000
    • addedInput schema / properties / subject / maxLength
      Added value: +1000
    • addedInput schema / properties / type / maxLength
      Added value: +1000
    • addedInput schema / properties / venue / maxLength
      Added value: +1000
    • addedOutput schema / properties / response_limited
      Added value: +{
      +  "type": "boolean"
      +}
  4. First observed

TDQS

A3.6/5.0
Behavior3/5

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 safety profile is covered. The description adds one genuinely useful behavioral fact, that facets span the whole filtered set before pagination, meaning offset/limit do not alter the facet population. It does not disclose what 'ranked' means (count descending?) or whether limit caps the facet list, which leaves real ambiguity about the response shape even with the lower bar annotations provide.

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?

Two short sentences, scoping fact first, cross-reference second, with zero filler. Nothing could be removed without losing information.

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?

An output schema exists, so return values need not be described, and the key non-obvious behavior (pre-pagination scope) is stated. What is missing is guidance on the required facet parameter and on how limit interacts with the ranked facet list, which matters for a 13-parameter tool.

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 69%, and the schema documents most filters (keyword, year_from/to, language, has_fulltext, etc.) well. The required 'facet' parameter has an enum but no description in the schema and no explanation in the description, which is the single most important semantic gap. The description's 'same selection rules as search_publications' does add cross-tool meaning for the filter parameters, justifying a solid 3 rather than lower.

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?

States a specific resource and scope: ranked facet counts computed over the entire filtered bibliography before pagination is applied. It also anchors itself to a named sibling (search_publications), so an agent can tell it apart from the plain search tool. It stops short of 5 because 'facet' is never explained in plain terms and the required facet parameter's meaning is left implicit.

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?

'Uses the same selection rules as search_publications' implies the intended workflow (apply filters, then read counts) and hints that filters are copied from the search tool. However, there is no explicit when-to-use versus alternatives such as list_years, list_subjects, list_categories, or list_journals, and no statement that this should replace those when a filtered count is needed.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.