Skip to main content
Glama

Search research items

search_research_items
Read-onlyIdempotent

Search digitised research items. Filters are AND-combined; empty results suggest a filter to relax or a stored place name. export links all matches as a file.

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": "search_research_items"
  }
}

Input Schema

NameRequiredDescriptionDefault
genreNoFormat term or physical note, partial (e.g. 'interview', 'photograph')
limitNoDefault 20, max 100
exportNoReturn a file link instead of rows
offsetNo
countryNoCountry only, exact name or common alias ('Côte d'Ivoire' = 'Ivory Coast'). Use `location` for cities
keywordNoEvery word must occur in the title, description, abstract, contents or identifiers; quote a phrase to match it exactly
subjectNoSubject heading, partial (e.g. 'Architecture'). Subjects absorb the former free-form tags — there is no tag filter
year_toNoKeep items whose content dates overlap up to this year
languageNoName or ISO code — 'French', 'fr', 'fra' and legacy 'fre' all match
locationNoA place at ANY level of the city→country hierarchy: 'Nigeria' finds Lagos items, 'Lagos' finds only Lagos
has_mediaNotrue: only items with digitised files
year_fromNoKeep items whose content dates overlap from this year
collectionNoCollection id, code or partial title from list_collections
project_idNoProject Omeka id
universityNoubt | unilag | ujkz | ufba | external — code or full name
added_sinceNoAdded to AMIRA on or after this ISO date
contributorNoA person/organisation credited on the item; either name order works
location_idNoExact location authority ID, including descendants; avoids homonym matches
resource_typeNoe.g. 'Image', 'Text', 'Audio', 'Moving image'
modified_sinceNoChanged on or after this ISO date
mentions_countryNoILAM African Music articles whose full text names this country 3+ times
research_sectionNoe.g. 'Arts & Aesthetics', 'Mobilities'

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / genre / description
      Previous value: -"Format/genre descriptor, partial (e.g. 'interview', 'letter', 'photograph')"New value: +"Format term or physical note, partial (e.g. 'interview', 'photograph')"
  2. Changed1 schema field changed
    • removedInput schema / $schema
      Removed value: -"https://json-schema.org/draft/2020-12/schema"
  3. Changed1 schema field changed
    • changedInput schema / properties / collection / description
      Previous value: -"Item-set title (partial) or id from list_collections"New value: +"Collection id, code or partial title from list_collections"
  4. Changed1 schema field changed
    • addedInput schema / properties / mentions_country
      Added value: +{
      +  "description": "ILAM African Music articles whose full text names this country 3+ times",
      +  "maxLength": 1000,
      +  "type": "string"
      +}
  5. Changed2 schema fields changed
    • removedInput schema / properties / limit / maximum
      Removed value: -9007199254740991
    • removedInput schema / properties / location_id / maximum
      Removed value: -9007199254740991
  6. Changed21 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 / collection / maxLength
      Added value: +1000
    • addedInput schema / properties / contributor / maxLength
      Added value: +1000
    • changedInput schema / properties / country / description
      Previous value: -"Only the country level of the hierarchy. Use `location` to match a city or any level"New value: +"Country only, exact name or common alias ('Côte d'Ivoire' = 'Ivory Coast'). Use `location` for cities"
    • addedInput schema / properties / country / maxLength
      Added value: +1000
    • addedInput schema / properties / export
      Added value: +{
      +  "description": "Return a file link instead of rows",
      +  "enum": [
      +    "csv",
      +    "jsonl"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / genre / maxLength
      Added value: +1000
    • addedInput schema / properties / has_media
      Added value: +{
      +  "description": "true: only items with digitised files",
      +  "type": "boolean"
      +}
    • changedInput schema / properties / keyword / description
      Previous value: -"Matches titles, description, abstract, table of contents and identifiers. Accent- and case-insensitive"New value: +"Every word must occur in the title, description, abstract, contents or identifiers; quote a phrase to match it exactly"
    • addedInput schema / properties / keyword / maxLength
      Added value: +1000
    • addedInput schema / properties / language / maxLength
      Added value: +1000
    • addedInput schema / properties / location / maxLength
      Added value: +1000
    • addedInput schema / properties / location_id
      Added value: +{
      +  "description": "Exact location authority ID, including descendants; avoids homonym matches",
      +  "exclusiveMinimum": 0,
      +  "maximum": 9007199254740991,
      +  "type": "integer"
      +}
    • addedInput schema / properties / modified_since
      Added value: +{
      +  "description": "Changed on or after this ISO date",
      +  "maxLength": 40,
      +  "type": "string"
      +}
    • addedInput schema / properties / project_id / anyOf
      Added value: +[
      +  {
      +    "maxLength": 1000,
      +    "type": "string"
      +  },
      +  {
      +    "type": "number"
      +  }
      +]
    • changedInput schema / properties / project_id / description
      Previous value: -"Project Omeka o:id (legacy project keys also work)"New value: +"Project Omeka id"
    • removedInput schema / properties / project_id / type
      Removed value: -[
      -  "string",
      -  "number"
      -]
    • addedInput schema / properties / research_section / maxLength
      Added value: +1000
    • addedInput schema / properties / resource_type / maxLength
      Added value: +1000
    • addedInput schema / properties / subject / maxLength
      Added value: +1000
    • addedInput schema / properties / university / maxLength
      Added value: +1000
  7. First observed

TDQS

A3.7/5.0
Behavior4/5

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

Annotations already declare this a read-only, idempotent, non-destructive, closed-world read. The description adds real behavioral context beyond that: filters combine with AND rather than OR, empty results are a filter problem, and export changes the response into a file link instead of rows. It does not mention result ordering, pagination caps, or permission scope.

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?

Three short sentences, zero filler, with the core search purpose front-loaded and the export behavior placed last where it belongs. The troubleshooting sentence about empty results is slightly terse and requires a small inference to apply.

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

Completeness3/5

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

The tool has 22 optional parameters and no output schema, and the description never characterizes the returned rows or pagination behavior beyond mentioning that export yields a file link. What it does cover (filter combination, empty results, export) is the highest-value part, so the gap is real but moderate.

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?

With 95% schema coverage the per-parameter documentation is already strong, and the description correctly avoids restating it. What it adds is cross-parameter semantics the schema cannot express: that all supplied filters are AND-combined, and that setting export converts the call from row-returning to a single file link.

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?

"Search digitised research items" gives a specific verb and resource that separates it from get_research_item and list_research_* siblings. It does not explicitly name which sibling to use for a single-item lookup or cross-domain search, so it stops short of full differentiation.

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?

The description implicitly covers usage by explaining that filters are AND-combined and that empty results mean a filter should be relaxed or a place name checked. It never states when to prefer this tool over sibling search tools such as search or search_publications, so guidance is contextual rather than explicit.

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.