AMIRA — Africa Multiple Research Data

by io.github.AM-Digital-Research-Environment

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.

Input Schema

Name	Required	Description
`genre`	No	Format/genre descriptor, partial (e.g. 'interview', 'letter', 'photograph')
`limit`	No	Default 20, max 100
`export`	No	Return a file link instead of rows
`offset`	No
`country`	No	Country only, exact name or common alias ('Côte d'Ivoire' = 'Ivory Coast'). Use `location` for cities
`keyword`	No	Every word must occur in the title, description, abstract, contents or identifiers; quote a phrase to match it exactly
`subject`	No	Subject heading, partial (e.g. 'Architecture'). Subjects absorb the former free-form tags — there is no tag filter
`year_to`	No	Keep items whose content dates overlap up to this year
`language`	No	Name or ISO code — 'French', 'fr', 'fra' and legacy 'fre' all match
`location`	No	A place at ANY level of the city→country hierarchy: 'Nigeria' finds Lagos items, 'Lagos' finds only Lagos
`has_media`	No	true: only items with digitised files
`year_from`	No	Keep items whose content dates overlap from this year
`collection`	No	Item-set title (partial) or id from list_collections
`project_id`	No	Project Omeka id
`university`	No	ubt \| unilag \| ujkz \| ufba \| external — code or full name
`added_since`	No	Added to AMIRA on or after this ISO date
`contributor`	No	A person/organisation credited on the item; either name order works
`location_id`	No	Exact location authority ID, including descendants; avoids homonym matches
`resource_type`	No	e.g. 'Image', 'Text', 'Audio', 'Moving image'
`modified_since`	No	Changed on or after this ISO date
`research_section`	No	e.g. 'Arts & Aesthetics', 'Mobilities'

Schema Changelog

Changes observed during successful MCP inspections.

Changed21 schema fields changedOct 7, 2026

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
```

First observedOct 7, 2026

TDQS

A3.7/5.0

Behavior4/5

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

Annotations already establish readOnly/idempotent/non-destructive, so the bar is lower. The description adds real behavioral context beyond that: filters combine with AND, empty results have a diagnosable cause, and export switches the response from rows to a file link rather than filtering differently.

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, front-loaded with the purpose. The middle sentence on AND semantics and empty results is high-value; the export sentence is brief and earns its place.

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?

For a 21-parameter read-only search with no output schema, the description covers the most consequential gotchas (AND logic, export mode, empty-result diagnosis). Return shape and pagination are left to the schema, which documents limit/offset, so nothing critical is missing.

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 95% with 21 documented parameters, so the schema carries nearly all parameter meaning. The description only gestures at the filter set and the export mode ('export links all matches as a file'), adding little syntax or constraint detail beyond the schema.

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 verb+resource ('Search digitised research items'), which clearly separates it from sibling searches like search_persons, search_publications and search_videos. It does not name any alternative directly, but the resource noun is distinct enough for disambiguation.

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?

It explains the AND-combination of filters and what empty results imply (relax a filter, or use a stored place name), which is genuinely useful usage context. However, it gives no explicit when-to-use vs. alternatives — nothing tells the agent when to prefer this over search or get_research_item.

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

All AMIRA — Africa Multiple Research Data 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.

Search research items

Input Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources