Skip to main content
Glama

List years

list_years
Read-onlyIdempotent

Research-item year/decade histogram with dated and undated counts. A date range counts in each spanned bucket. dated_items and year_range follow from/to. Supports item filters and paging.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "list_years"
  }
}

Input Schema

NameRequiredDescriptionDefault
toNoLatest year to report (inclusive)
fromNoEarliest year to report (inclusive)
sortNoDefault 'chronological' (oldest first); 'count' ranks by item count
limitNoDefault 200, max 500
bucketNoDefault 'year'
offsetNo
filtersNoResearch-item filters applied before bucketing

Output Schema

NameRequiredDescriptionDefault
sortYes
countYes
bucketYes
offsetYes
resultsYes
has_moreYes
year_rangeNo
dated_itemsYes
next_offsetNo
total_matchesYes
undated_itemsYes
distinct_bucketsYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 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 / properties / results / items / additionalProperties
      Removed value: -false
    • removedOutput schema / properties / year_range / additionalProperties
      Removed value: -false
  2. Changed1 schema field changed
    • addedInput schema / properties / filters / properties / mentions_country
      Added value: +{
      +  "maxLength": 1000,
      +  "type": "string"
      +}
  3. Changed3 schema fields changed
    • removedInput schema / properties / filters / properties / location_id / maximum
      Removed value: -9007199254740991
    • changedInput schema / properties / filters / properties / project_id / anyOf
      Previous value: -[
      -  {
      -    "maxLength": 256,
      -    "type": "string"
      -  },
      -  {
      -    "exclusiveMinimum": 0,
      -    "maximum": 9007199254740991,
      -    "type": "integer"
      -  }
      -]New value: +[
      +  {
      +    "maxLength": 256,
      +    "type": "string"
      +  },
      +  {
      +    "exclusiveMinimum": 0,
      +    "type": "integer"
      +  }
      +]
    • removedInput schema / properties / limit / maximum
      Removed value: -9007199254740991
  4. Changed2 schema fields changed
    • addedInput schema / properties / filters
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "Research-item filters applied before bucketing",
      +  "properties": {
      +    "added_since": {
      +      "maxLength": 40,
      +      "type": "string"
      +    },
      +    "collection": {
      +      "maxLength": 1000,
      +      "type": "string"
      +    },
      +    "contributor": {
      +      "maxLength": 1000,
      +      "type": "string"
      +    },
      +    "country": {
      +      "maxLength": 1000,
      +      "type": "string"
      +    },
      +    "genre": {
      +      "maxLength": 1000,
      +      "type": "string"
      +    },
      +    "has_media": {
      +      "type": "boolean"
      +    },
      +    "keyword": {
      +      "maxLength": 1000,
      +      "type": "string"
      +    },
      +    "language": {
      +      "maxLength": 1000,
      +      "type": "string"
      +    },
      +    "location": {
      +      "maxLength": 1000,
      +      "type": "string"
      +    },
      +    "location_id": {
      +      "exclusiveMinimum": 0,
      +      "maximum": 9007199254740991,
      +      "type": "integer"
      +    },
      +    "modified_since": {
      +      "maxLength": 40,
      +      "type": "string"
      +    },
      +    "project_id": {
      +      "anyOf": [
      +        {
      +          "maxLength": 256,
      +          "type": "string"
      +        },
      +        {
      +          "exclusiveMinimum": 0,
      +          "maximum": 9007199254740991,
      +          "type": "integer"
      +        }
      +      ]
      +    },
      +    "research_section": {
      +      "maxLength": 1000,
      +      "type": "string"
      +    },
      +    "resource_type": {
      +      "maxLength": 1000,
      +      "type": "string"
      +    },
      +    "subject": {
      +      "maxLength": 1000,
      +      "type": "string"
      +    },
      +    "university": {
      +      "maxLength": 1000,
      +      "type": "string"
      +    },
      +    "year_from": {
      +      "maximum": 2200,
      +      "minimum": 0,
      +      "type": "integer"
      +    },
      +    "year_to": {
      +      "maximum": 2200,
      +      "minimum": 0,
      +      "type": "integer"
      +    }
      +  },
      +  "type": "object"
      +}
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$schema": "https://json-schema.org/draft/2020-12/schema",
      +  "additionalProperties": {},
      +  "properties": {
      +    "bucket": {
      +      "type": "string"
      +    },
      +    "count": {
      +      "type": "number"
      +    },
      +    "dated_items": {
      +      "type": "number"
      +    },
      +    "distinct_buckets": {
      +      "type": "number"
      +    },
      +    "has_more": {
      +      "type": "boolean"
      +    },
      +    "next_offset": {
      +      "type": "number"
      +    },
      +    "offset": {
      +      "type": "number"
      +    },
      +    "results": {
      +      "items": {
      +        "additionalProperties": false,
      +        "properties": {
      +          "decade": {
      +            "type": "string"
      +          },
      +          "from": {
      +            "type": "number"
      +          },
      +          "item_count": {
      +            "type": "number"
      +          },
      +          "to": {
      +            "type": "number"
      +          },
      +          "year": {
      +            "type": "number"
      +          }
      +        },
      +        "required": [
      +          "item_count"
      +        ],
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "sort": {
      +      "type": "string"
      +    },
      +    "total_matches": {
      +      "type": "number"
      +    },
      +    "undated_items": {
      +      "type": "number"
      +    },
      +    "year_range": {
      +      "additionalProperties": false,
      +      "properties": {
      +        "max": {
      +          "type": "number"
      +        },
      +        "min": {
      +          "type": "number"
      +        }
      +      },
      +      "required": [
      +        "min",
      +        "max"
      +      ],
      +      "type": "object"
      +    }
      +  },
      +  "required": [
      +    "count",
      +    "total_matches",
      +    "offset",
      +    "has_more",
      +    "bucket",
      +    "sort",
      +    "distinct_buckets",
      +    "dated_items",
      +    "undated_items",
      +    "results"
      +  ],
      +  "type": "object"
      +}
  5. First observed

TDQS

A3.8/5.0
Behavior4/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's job is to add aggregation semantics — and it does: undated counts are included alongside dated ones, and a spanning date range is counted in every bucket it touches, which is a genuinely non-obvious counting rule an agent could otherwise get wrong. It also notes that dated_items and year_range in the response are driven by from/to. It does not mention result ordering defaults or what happens when bucket='decade' interacts with from/to, but that is a minor gap.

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?

Four short sentences, front-loaded with the output shape, then the counting rule, then parameter effects, then filters/paging — a sensible information hierarchy with no filler. The phrasing is telegraphic ('dated_items and year_range follow from/to'), which is dense but not padded.

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 an output schema present, the description needn't enumerate return fields, and the nested filter object is documented in the schema itself. Given a 7-parameter tool with a 20-key nested filters object, the description covers what the schema cannot: bucket counting semantics and how the range parameters propagate into the response. Enough for an agent to invoke it correctly.

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 high (86%), so baseline is 3; the description earns above that by explaining non-obvious parameter effects — how from/to shape both bucket inclusion ('each spanned bucket') and the derived dated_items/year_range outputs — and by stating that filters are applied before bucketing, which clarifies the ordering of operations. It adds nothing about sort/limit/offset beyond the schema, but those are already documented.

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 names a specific resource and aggregation shape — 'Research-item year/decade histogram with dated and undated counts' — which immediately distinguishes it from the flat listing siblings like list_categories or list_collections. It stops short of an explicit verb ('return counts of items grouped by...'), but the resource plus aggregation type is unambiguous.

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?

'Supports item filters and paging' implies the context in which filters/paging apply, and the histogram framing implies 'use this to see distribution over time rather than to retrieve items.' However there is no explicit when-to-use, no when-not-to-use, and no pointer to which sibling to call instead if the agent actually wants item records (e.g. search or list_publication_facets).

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.