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.

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": {
      "query": "<query>"
    },
    "name": "smithsonian_search_objects"
  }
}

Input Schema

Name	Required	Description
`rows`	No	Page size (default 20). A value above 1000 is served at 1000 with a notice.
`query`	Yes	Free-text search. Every word is required — OR does not widen a search, while NOT excludes. 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. A key outside this set is rejected by name.

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. Opens with the page size served when rows exceeded its cap.
`objects`	No	Curated object summaries for the current page.
`sources`	No	Where this answer came from. A page served from oa_mirror lists its rows in mirror order, not the live API's, and its notice names the snapshot date. Present only on a server that keeps a mirror.
`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.
`mirror_snapshot`	No	Publication time (ISO 8601) of the Open Access snapshot the mirror held; what came from oa_mirror reflects the catalog as of then. Present when part of this answer came from oa_mirror.
`truncationCeiling`	No	Total matching objects (upper bound for omitted items).

Schema Changelog

Changes observed during successful MCP inspections.

Changed12 schema fields changedNov 1, 2026

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

changedInput schema / properties / filters / description

Previous value: -"Optional structured filters to narrow the search."New value: +"Optional structured filters to narrow the search. A key outside this set is rejected by name."

changedInput schema / properties / filters / properties / place / description

Previous value: -"Geographic place (e.g. \"United States of America\"). The full set is enumerable via smithsonian_list_terms (field \"place\")."New value: +"Geographic place term, matched exactly (e.g. \"United States\"). Variants are separate terms with no hierarchy — \"United States of America\" is a different, far smaller term, and a record filed under a state alone carries no country term. The full set is enumerable via smithsonian_list_terms (field \"place\")."

changedInput schema / properties / filters / properties / scientific_name / description

Previous value: -"Exact indexed scientific name from smithsonian_get_object.scientific_names, e.g. \"Crotalus horridus\". Not enumerable via smithsonian_list_terms."New value: +"Exact indexed scientific name from smithsonian_get_object.scientific_names, e.g. \"Crotalus horridus\"; a bare genus (\"Crotalus\") also matches, across its species. Not enumerable via smithsonian_list_terms."

changedInput schema / properties / query / description

Previous value: -"Free-text search. Use specific terms for precision (\"Tlingit totem pole\") or broad terms for browsing (\"quilt\")."New value: +"Free-text search. Every word is required — OR does not widen a search, while NOT excludes. Use specific terms for precision (\"Tlingit totem pole\") or broad terms for browsing (\"quilt\")."

changedInput schema / properties / rows / description

Previous value: -"Page size (default 20, max 100)."New value: +"Page size (default 20). A value above 1000 is served at 1000 with a notice."

removedInput schema / properties / rows / maximum
```
Removed value: -100
```
addedInput schema / properties / rows / multipleOf
```
Added value: +1
```

addedOutput schema / properties / mirror_snapshot

Added value: +{
+  "description": "Publication time (ISO 8601) of the Open Access snapshot the mirror held; what came from oa_mirror reflects the catalog as of then. Present when part of this answer came from oa_mirror.",
+  "type": "string"
+}

changedOutput schema / properties / notice / description

Previous value: -"Guidance naming the input that retrieves the objects this page omitted."New value: +"Guidance naming the input that retrieves the objects this page omitted. Opens with the page size served when rows exceeded its cap."

addedOutput schema / properties / objects / items / properties / holding_museum_name

Added value: +{
+  "description": "The unit that holds the object, from the record's own data source, when it differs from the unit that indexes it (unit_code). Absent otherwise.",
+  "type": "string"
+}

addedOutput schema / properties / sources

Added value: +{
+  "description": "Where this answer came from. A page served from oa_mirror lists its rows in mirror order, not the live API's, and its notice names the snapshot date. Present only on a server that keeps a mirror.",
+  "items": {
+    "description": "oa_mirror: the server's local copy of the Smithsonian Open Access bulk metadata. edan_api: the live Smithsonian API.",
+    "enum": [
+      "oa_mirror",
+      "edan_api"
+    ],
+    "type": "string"
+  },
+  "type": "array"
+}

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 declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds useful behavioral context by saying results are curated summaries with title, date, museum, thumbnail URL, CC0 flag, and total match count, and by explaining how filters and record_id connect to other tools; it does not add permission or rate-limit details, but that is not critical given the annotations.

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?

The description is front-loaded with the primary recommendation and scope, then covers filter behavior, return content, record_id routing, and the browse alternative. Every sentence serves tool selection or invocation, with no redundant restatement of the tool name.

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?

Given the output schema, annotations, and 100% parameter coverage, the description supplies what an agent needs: when to choose it, what it returns, how filters work at a high level, and how record_id links to sibling tools. It also names the alternative for exact-category browsing, leaving no major selection or invocation gap.

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%, so the schema already carries detailed parameter semantics, including examples and edge cases for filters such as name, object_type, and online_only. The description adds only a high-level list of filter categories and the idea that filters are exact, so it does not meaningfully exceed the schema's own explanations.

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?

The description states a specific verb and resource: free-text search across 14.5 million Smithsonian objects with optional exact filters. It distinguishes this from smithsonian_browse_category and names the record_id linkage to smithsonian_get_object, smithsonian_find_related, and smithsonian_get_media, so an agent can identify the tool's role without opening the 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?

It explicitly recommends this as the first step for open-ended or topic discovery and says to use smithsonian_browse_category instead when browsing one exact category such as a museum, culture, date term, object type, or topic. It also gives downstream guidance by identifying record_id as the identifier for the related object, media, and related-record tools.

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.