smithsonian-mcp-server

Search Smithsonian Objects

smithsonian_search_objects

Read-onlyIdempotent

Recommended first step for open-ended or topic discovery: free-text search across 14.5 million Smithsonian objects, with optional exact filters. Filters narrow by museum unit, object type, indexed date term, culture, geographic place, subject topic, named party, and online/CC0 availability. Returns curated summaries (title, date, museum, thumbnail URL, CC0 flag) with the total match count. The record_id in each result is the identifier for smithsonian_get_object, smithsonian_find_related, and smithsonian_get_media. To browse one exact category — a single museum, culture, date term, object type, or topic — use smithsonian_browse_category instead.

Input Schema

Name	Required	Description
`rows`	No	Page size (default 20, max 100).
`query`	Yes	Free-text search. Use specific terms for precision ("Tlingit totem pole") or broad terms for browsing ("quilt").
`start`	No	Pagination offset — 0-indexed. Use with rows for paging through large result sets.
`filters`	No	Optional structured filters to narrow the search.

Output Schema

Name	Required	Description
`cap`	No	The rows cap that was applied.
`error`	No	Present when the call failed. Absent on success.
`shown`	No	Number of objects returned in this page.
`notice`	No	Guidance naming the input that retrieves the objects this page omitted.
`objects`	No	Curated object summaries for the current page.
`truncated`	No	True when matching objects remain past this page. False on a terminal or past-the-end page, where nothing is being withheld.
`total_count`	No	Total matching objects in the Smithsonian catalog before pagination.
`truncationCeiling`	No	Total matching objects (upper bound for omitted items).

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedOct 18, 2026

addedInput schema / properties / filters / properties / online_media_type

Added value: +{
+  "description": "Exact indexed media category from smithsonian_list_terms { field: \"online_media_type\" }, e.g. \"Images\", \"3D Models\", \"Sound recordings\". Even Images does not guarantee attached or CC0 images; read smithsonian_get_object.media_summary for availability.",
+  "type": "string"
+}

addedInput schema / properties / filters / properties / scientific_name

Added value: +{
+  "description": "Exact indexed scientific name from smithsonian_get_object.scientific_names, e.g. \"Crotalus horridus\". Not enumerable via smithsonian_list_terms.",
+  "type": "string"
+}

Changed6 schema fields changedAug 25, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "objects",
+      "total_count"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `no_results`: An unfiltered query matched no objects. `invalid_filter`: A filtered search matched nothing — most often a filter value outside the Smithsonian controlled vocabulary (e.g. a singular \"Painting\" instead of \"Paintings\"). Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "no_results",
+            "invalid_filter"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

removedOutput schema / required

Removed value: -[
-  "objects",
-  "total_count"
-]

Changed2 schema fields changedJul 26, 2026

changedInput schema / properties / filters / properties / object_type / description

Previous value: -"Object type term from Smithsonian's controlled vocabulary — commonly plural (e.g. \"Paintings\", \"Photographs\", \"Aircraft\"). Singular everyday forms like \"Painting\" usually return nothing. This field is not enumerable via smithsonian_list_terms; harvest valid values from the object_type field in smithsonian_search_objects results."New value: +"Object type term from Smithsonian's controlled vocabulary — commonly plural (e.g. \"Paintings\", \"Photographs\", \"Aircraft\"). Singular everyday forms like \"Painting\" usually return nothing. This field is not enumerable via smithsonian_list_terms; harvest valid values from the object_type field in smithsonian_search_objects results. Matched exactly and case-sensitively, and casing variants are indexed as SEPARATE categories — \"button\" and \"Button\" each hold their own records, and neither casing is reliably the larger — so probe a harvested value's other casings rather than assuming one covers the concept."

changedOutput schema / properties / objects / items / properties / object_type / description

Previous value: -"Object type term (e.g. \"Aircraft\", \"Paintings\", \"Photographs\")."New value: +"Object type term (e.g. \"Aircraft\", \"Paintings\", \"Photographs\"). Harvest it here to filter a later search, but it is case-sensitive and casing variants are separate categories upstream — this row carries one casing of the concept, not all of it."

Changed2 schema fields changedJul 26, 2026

addedInput schema / properties / filters / properties / name

Added value: +{
+  "description": "Indexed named party — maker, collector, donor, issuing authority, or any other role the catalog records. Written surname-first (e.g. \"Warhol, Andy\"). This field is not enumerable via smithsonian_list_terms. A smithsonian_find_related name signal carries the indexed form verbatim and is the reliable source; smithsonian_get_object's makers[] is the catalog's free-text form of the same parties and is often written differently (\"Major J. A. L. Möller (Jacob A.L. Möller/Monty Möller), Non-Indian, 1883-1957\" for the indexed \"Möller, Major J. A. L.\"), so treat it as a starting guess.",
+  "type": "string"
+}

addedInput schema / properties / filters / properties / topic

Added value: +{
+  "description": "Subject term from the controlled vocabulary (e.g. \"Quilts\", \"Aviation\"). Matches the topics[] values smithsonian_get_object returns, and is a hard constraint — topic \"Quilts\" matches 1,134 objects where the same word as free text matches 2,677. The full set is enumerable via smithsonian_list_terms (field \"topic\").",
+  "type": "string"
+}

Changed5 schema fields changedJul 26, 2026

changedInput schema / properties / filters / properties / cc0_only / description

Previous value: -"When true, restrict to CC0 open-access objects. Useful before calling smithsonian_get_media."New value: +"When true, restrict to records that have CC0-licensed media attached (the Lucene term media_usage:CC0). This selects on media presence, not license status — the roughly 9.2M records it excludes are CC0 too, they simply have nothing digitized. Read has_media on each result to decide whether smithsonian_get_media will return anything."

addedInput schema / properties / filters / properties / date

Added value: +{
+  "description": "Indexed date term. Decades (\"1920s\", \"1960s\") are the most common form, but the vocabulary also carries year ranges (\"500-1500\"), century terms (\"21st century\"), and BCE forms (\"-2500\", \"BCE 1000s\"). The value must be an exact term — the full set is enumerable via smithsonian_list_terms (field \"date\").",
+  "type": "string"
+}

removedInput schema / properties / filters / properties / date_decade

Removed value: -{
-  "description": "Decade filter (e.g. \"1920s\", \"1960s\"). Must match the \"NNNNs\" format exactly. Indexed decades are enumerable via smithsonian_list_terms (field \"date\").",
-  "pattern": "^\\d{4}s$",
-  "type": "string"
-}

changedOutput schema / properties / objects / items / properties / date / description

Previous value: -"Decade-level date the catalog indexes for the object (e.g. \"1960s\"). Sparse — omitted when the record has no indexed date."New value: +"Indexed date term for the object — commonly a decade (\"1960s\"), but the vocabulary also carries year ranges (\"500-1500\"), century terms (\"21st century\"), and BCE forms (\"-2500\", \"BCE 1000s\"). Sparse — omitted when the record has no indexed date."

changedOutput schema / properties / objects / items / properties / is_cc0 / description

Previous value: -"True when the object metadata is CC0 (open access). Use smithsonian_get_media for CC0 image downloads."New value: +"True when the object metadata is CC0 (open access). The Smithsonian Open Access corpus is CC0 throughout, so this flag rarely varies and cannot gate an image download — read has_media for that."

AddedJul 25, 2026

TDQS

A4.5/5.0

Behavior4/5

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, openWorldHint), so the bar is lower. The description nonetheless adds corpus scale (14.5M objects), the fact that filters are exact-match constraints, the total match count in the response, and — crucially — that each result's record_id is the chaining key for smithsonian_get_object, smithsonian_find_related, and smithsonian_get_media.

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?

Three sentences, each doing distinct work: purpose and scale, filter overview and return shape, then identifier chaining and the sibling alternative. Front-loaded with the disambiguating scope statement and no filler.

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

Completeness5/5

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

For a 4-parameter search tool with a 100%-covered nested schema, an output schema, and full annotations, nothing an agent needs is missing: purpose, filter scope, return fields, chaining keys, and the sibling alternative are all present.

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 100% and the nested filters object is exhaustively documented in the schema itself (including vocabulary sources and edge cases), so the schema does the heavy lifting. The description only enumerates the filter categories at a high level ('museum unit, object type, indexed date term, culture, geographic place, subject topic, named party, and online/CC0 availability'), which restates rather than extends the schema.

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

Purpose5/5

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

States a specific verb and resource ('free-text search across 14.5 million Smithsonian objects') and frames its position in the workflow ('Recommended first step for open-ended or topic discovery'). It explicitly contrasts itself with smithsonian_browse_category, so an agent can distinguish the two without opening either schema.

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

Usage Guidelines5/5

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

Gives an explicit when-to-use condition (open-ended/topic discovery with free text) and names the alternative with its own condition ('To browse one exact category ... use smithsonian_browse_category instead'). It also notes the filters are 'exact' versus the free-text query, which tells the agent how to combine them.

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

All smithsonian-mcp-server 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.