Skip to main content
Glama

smithsonian-mcp-server

by io.github.cyanheads
OverviewDiscussionsAdmin

Find Related Smithsonian Objects

smithsonian_find_related
Read-onlyIdempotent

Discover objects across Smithsonian collections related to a given anchor object, matched on shared metadata signals — culture, period, object type, named parties, and topic terms. Each related object is tagged with the signals that connected it to the anchor; a named-party signal carries the catalog's own role for that party (maker, Collector, Donor, issuing authority, …), not a fixed "maker" label. Matches surface across museums — an NASM aerospace anchor can pull related objects from NMNHPALEO, SAAM, and NMAH.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
idYesrecord_id of the anchor object (e.g. "nasm_A19670093000") from smithsonian_search_objects or smithsonian_get_object.
limitNoMaximum number of related objects to return (default 10, max 20).
startNoPagination offset — 0-indexed. Page contiguously with start = page × limit; each signal is reachable to a depth of 5000 objects, beyond which truncated stays true but deeper pages aren't retrievable.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
capNoThe limit cap that was applied.
errorNoPresent when the call failed. Absent on success.
shownNoNumber of related objects returned.
anchorNoSummary of the anchor object used to drive the fan-out searches.
noticeNoGuidance naming the inputs that retrieve the related objects this page omitted — start for the next page, signals[].search_continuation for a signal past this tool's reach.
relatedNoRelated objects interleaved across the fan-out signals so each signal contributes. Empty when no related objects were found across all fan-out searches.
signalsNoPer-signal breakdown of every fan-out that returned. Use search_continuation with smithsonian_search_objects to retrieve a signal's matches past this tool's 5000-per-signal reach. A signal whose upstream call failed is omitted.
truncatedNoTrue when the related list is incomplete — either capped by the limit or more results exist upstream past the current page (advance start to retrieve them).
truncationCeilingNoUpper bound on the related objects reachable by paging with start. Cross-signal overlaps are not subtracted, so it can overcount. Signals larger than this tool's per-signal reach are counted at that reach — see signals[].row_count for their true size.
search_signals_usedNoMetadata fields that drove the fan-out searches.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 schema fields changed
    • 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": [
+      "anchor",
+      "related",
+      "search_signals_used",
+      "signals"
+    ]
+  },
+  {
+    "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: `not_found`: The anchor object ID does not exist in the Smithsonian catalog. `invalid_id`: The ID is empty or contains only whitespace. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "not_found",
+            "invalid_id"
+          ],
+          "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: -[
-  "anchor",
-  "related",
-  "search_signals_used",
-  "signals"
-]
  2. Changed2 schema fields changed
    • addedOutput schema / properties / signals / items / properties / search_continuation / properties / filters / properties / name
      Added value: +{
+  "description": "smithsonian_search_objects filters.name value.",
+  "type": "string"
+}
    • addedOutput schema / properties / signals / items / properties / search_continuation / properties / filters / properties / topic
      Added value: +{
+  "description": "smithsonian_search_objects filters.topic value.",
+  "type": "string"
+}
  3. Changed3 schema fields changed
    • changedOutput schema / properties / related / items / properties / is_cc0 / description
      Previous value: -"True when the object is CC0 open access."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 thumbnail_url for that."
    • addedOutput schema / properties / signals / items / properties / search_continuation / properties / filters / properties / date
      Added value: +{
+  "description": "smithsonian_search_objects filters.date value.",
+  "type": "string"
+}
    • removedOutput schema / properties / signals / items / properties / search_continuation / properties / filters / properties / date_decade
      Removed value: -{
-  "description": "smithsonian_search_objects filters.date_decade value.",
-  "type": "string"
-}
  4. Changed8 schema fields changed
    • changedInput schema / properties / id / description
      Previous value: -"record_id of the anchor object (e.g. \"nasm_A19670093000\") from smithsonian_search or smithsonian_get_object."New value: +"record_id of the anchor object (e.g. \"nasm_A19670093000\") from smithsonian_search_objects or smithsonian_get_object."
    • changedOutput schema / properties / signals / description
      Previous value: -"Per-signal breakdown of every fan-out that returned. Use search_continuation with smithsonian_search to retrieve a signal's matches past this tool's 5000-per-signal reach. A signal whose upstream call failed is omitted."New value: +"Per-signal breakdown of every fan-out that returned. Use search_continuation with smithsonian_search_objects to retrieve a signal's matches past this tool's 5000-per-signal reach. A signal whose upstream call failed is omitted."
    • changedOutput schema / properties / signals / items / properties / search_continuation / description
      Previous value: -"Exact smithsonian_search input that reproduces this signal's full match set, at any depth."New value: +"Exact smithsonian_search_objects input that reproduces this signal's full match set, at any depth."
    • changedOutput schema / properties / signals / items / properties / search_continuation / properties / filters / description
      Previous value: -"Pass verbatim as smithsonian_search's filters. Omitted when the signal's constraint is already carried entirely by query."New value: +"Pass verbatim as smithsonian_search_objects's filters. Omitted when the signal's constraint is already carried entirely by query."
    • changedOutput schema / properties / signals / items / properties / search_continuation / properties / filters / properties / culture / description
      Previous value: -"smithsonian_search filters.culture value."New value: +"smithsonian_search_objects filters.culture value."
    • changedOutput schema / properties / signals / items / properties / search_continuation / properties / filters / properties / date_decade / description
      Previous value: -"smithsonian_search filters.date_decade value."New value: +"smithsonian_search_objects filters.date_decade value."
    • changedOutput schema / properties / signals / items / properties / search_continuation / properties / filters / properties / object_type / description
      Previous value: -"smithsonian_search filters.object_type value."New value: +"smithsonian_search_objects filters.object_type value."
    • changedOutput schema / properties / signals / items / properties / search_continuation / properties / query / description
      Previous value: -"Pass verbatim as smithsonian_search's query. Empty when the signal is expressed entirely through filters."New value: +"Pass verbatim as smithsonian_search_objects's query. Empty when the signal is expressed entirely through filters."
  5. Changed4 schema fields changed
    • addedOutput schema / properties / notice
      Added value: +{
+  "description": "Guidance naming the inputs that retrieve the related objects this page omitted — start for the next page, signals[].search_continuation for a signal past this tool's reach.",
+  "type": "string"
+}
    • addedOutput schema / properties / signals
      Added value: +{
+  "description": "Per-signal breakdown of every fan-out that returned. Use search_continuation with smithsonian_search to retrieve a signal's matches past this tool's 5000-per-signal reach. A signal whose upstream call failed is omitted.",
+  "items": {
+    "additionalProperties": false,
+    "description": "One fan-out signal with its true size and its retrieval path.",
+    "properties": {
+      "row_count": {
+        "description": "True upstream match count for this signal, uncapped — it can exceed the 5000-per-signal depth this tool's own paging reaches.",
+        "type": "number"
+      },
+      "search_continuation": {
+        "additionalProperties": false,
+        "description": "Exact smithsonian_search input that reproduces this signal's full match set, at any depth.",
+        "properties": {
+          "filters": {
+            "additionalProperties": false,
+            "description": "Pass verbatim as smithsonian_search's filters. Omitted when the signal's constraint is already carried entirely by query.",
+            "properties": {
+              "culture": {
+                "description": "smithsonian_search filters.culture value.",
+                "type": "string"
+              },
+              "date_decade": {
+                "description": "smithsonian_search filters.date_decade value.",
+                "type": "string"
+              },
+              "object_type": {
+                "description": "smithsonian_search filters.object_type value.",
+                "type": "string"
+              }
+            },
+            "type": "object"
+          },
+          "query": {
+            "description": "Pass verbatim as smithsonian_search's query. Empty when the signal is expressed entirely through filters.",
+            "type": "string"
+          }
+        },
+        "required": [
+          "query"
+        ],
+        "type": "object"
+      },
+      "signal": {
+        "description": "Matches an entry in search_signals_used and in related[].similarity_signals.",
+        "type": "string"
+      }
+    },
+    "required": [
+      "signal",
+      "row_count",
+      "search_continuation"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}
    • changedOutput schema / properties / truncationCeiling / description
      Previous value: -"Upper bound on the related objects reachable by paging with start. Cross-signal overlaps are not subtracted, so it can overcount."New value: +"Upper bound on the related objects reachable by paging with start. Cross-signal overlaps are not subtracted, so it can overcount. Signals larger than this tool's per-signal reach are counted at that reach — see signals[].row_count for their true size."
    • changedOutput schema / required
      Previous value: -[
-  "anchor",
-  "related",
-  "search_signals_used"
-]New value: +[
+  "anchor",
+  "related",
+  "search_signals_used",
+  "signals"
+]
  6. Changed1 schema field changed
    • changedOutput schema / properties / related / items / properties / museum_name / description
      Previous value: -"Full museum name."New value: +"Full museum name. A few rarely-indexed archive sub-unit codes have no mapped name and fall back to the raw unit code."
  7. Changed2 schema fields changed
    • changedInput schema / properties / start / description
      Previous value: -"Pagination offset into the interleaved related-object sequence — 0-indexed. Page contiguously with start = page × limit: page N+1 continues where page N ended. Each contributing signal is reachable to a depth of 5000 objects (fetched in chunks upstream), so deep pages of a broad signal are retrievable. Near a page seam a small, bounded number of objects (up to the active-signal count) can shift by one page when a deeper page surfaces an object that ranks very differently across signals. Beyond 5000 matches for a signal, truncated stays true but deeper pages aren't reachable."New value: +"Pagination offset — 0-indexed. Page contiguously with start = page × limit; each signal is reachable to a depth of 5000 objects, beyond which truncated stays true but deeper pages aren't retrievable."
    • changedOutput schema / properties / truncationCeiling / description
      Previous value: -"Upper bound on the reachable related objects across the contributing signals — each signal’s upstream match count is capped at its per-signal reach before summing, so the ceiling never exceeds what paging with start can actually retrieve. Cross-signal overlaps are not subtracted."New value: +"Upper bound on the related objects reachable by paging with start. Cross-signal overlaps are not subtracted, so it can overcount."
  8. Changed2 schema fields changed
    • changedInput schema / properties / start / description
      Previous value: -"Pagination offset into the interleaved related-object sequence — 0-indexed. Page contiguously with start = page × limit: page N+1 continues where page N ended, within the first 100 related objects per signal. Near a page seam a small, bounded number of objects (up to the active-signal count) can shift by one page when a deeper page surfaces an object that ranks very differently across signals. Beyond the cap, truncated stays true but deeper pages aren't reachable."New value: +"Pagination offset into the interleaved related-object sequence — 0-indexed. Page contiguously with start = page × limit: page N+1 continues where page N ended. Each contributing signal is reachable to a depth of 5000 objects (fetched in chunks upstream), so deep pages of a broad signal are retrievable. Near a page seam a small, bounded number of objects (up to the active-signal count) can shift by one page when a deeper page surfaces an object that ranks very differently across signals. Beyond 5000 matches for a signal, truncated stays true but deeper pages aren't reachable."
    • changedOutput schema / properties / truncationCeiling / description
      Previous value: -"Upper bound on total related objects across the contributing signals (sum of each fan-out signal’s upstream match count; cross-signal overlaps are not subtracted)."New value: +"Upper bound on the reachable related objects across the contributing signals — each signal’s upstream match count is capped at its per-signal reach before summing, so the ceiling never exceeds what paging with start can actually retrieve. Cross-signal overlaps are not subtracted."
  9. Changed3 schema fields changed
    • addedInput schema / properties / start
      Added value: +{
+  "default": 0,
+  "description": "Pagination offset into the interleaved related-object sequence — 0-indexed. Page contiguously with start = page × limit: page N+1 continues where page N ended, within the first 100 related objects per signal. Near a page seam a small, bounded number of objects (up to the active-signal count) can shift by one page when a deeper page surfaces an object that ranks very differently across signals. Beyond the cap, truncated stays true but deeper pages aren't reachable.",
+  "maximum": 9007199254740991,
+  "minimum": 0,
+  "type": "integer"
+}
    • changedOutput schema / properties / truncated / description
      Previous value: -"True when the related list was capped by the limit parameter."New value: +"True when the related list is incomplete — either capped by the limit or more results exist upstream past the current page (advance start to retrieve them)."
    • addedOutput schema / properties / truncationCeiling
      Added value: +{
+  "description": "Upper bound on total related objects across the contributing signals (sum of each fan-out signal’s upstream match count; cross-signal overlaps are not subtracted).",
+  "type": "number"
+}
  10. Changed1 schema field changed
    • changedOutput schema / required
      Previous value: -[
-  "anchor",
-  "related",
-  "search_signals_used",
-  "truncated",
-  "shown",
-  "cap"
-]New value: +[
+  "anchor",
+  "related",
+  "search_signals_used"
+]
  11. Changed4 schema fields changed
    • addedOutput schema / properties / cap
      Added value: +{
+  "description": "The limit cap that was applied.",
+  "type": "number"
+}
    • addedOutput schema / properties / shown
      Added value: +{
+  "description": "Number of related objects returned.",
+  "type": "number"
+}
    • addedOutput schema / properties / truncated
      Added value: +{
+  "description": "True when the related list was capped by the limit parameter.",
+  "type": "boolean"
+}
    • changedOutput schema / required
      Previous value: -[
-  "anchor",
-  "related",
-  "search_signals_used"
-]New value: +[
+  "anchor",
+  "related",
+  "search_signals_used",
+  "truncated",
+  "shown",
+  "cap"
+]
  12. Changed1 schema field changed
    • changedOutput schema / properties / related / description
      Previous value: -"Related objects ranked by number of matching metadata signals. Empty when no related objects were found across all fan-out searches."New value: +"Related objects interleaved across the fan-out signals so each signal contributes. Empty when no related objects were found across all fan-out searches."
  13. First observed

TDQS

A4.3/5.0
Behavior4/5

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

The description adds context beyond the readOnlyHint, openWorldHint, and idempotentHint annotations by explaining the matching logic, the dynamic role field for named parties, and the cross-museum behavior. It does not contradict any annotations. The description is informative but could mention error conditions or the depth limit on pagination, though that is also in the schema. Overall, it complements the annotations well.

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 two sentences with no fluff: the first sentence states the core function and matching signals, and the second adds the cross-museum nuance and the role semantics. Information is front-loaded, and every clause adds value. The length is appropriate for the complexity.

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 exists (so return format is covered) and the description explains the matching signals, the role field nuance, and cross-museum behavior, an agent has enough contextual information to decide when to call this tool and what to expect. The example anchors to other tools (search/get) also helps. No critical missing context is apparent for the tool's complexity.

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 coverage is 100%, with each parameter (id, limit, start) having a clear description in the schema. The tool description does not add additional parameter semantics beyond what the schema already provides. It explains the anchor's example and the meaning of signals, but that relates to output and context, not parameter meaning. Baseline 3 is appropriate since the schema handles the documentation.

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 clearly states the tool's purpose: discovering related objects across Smithsonian collections based on shared metadata signals. It lists specific signal types and gives a cross-museum example, making it distinct from search, get, browse, and list tools. This is a specific verb-resource-scope combination that an agent can immediately understand.

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

Usage Guidelines4/5

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

It provides context about the input anchor (from smithsonian_search_objects or smithsonian_get_object) and explains the matching mechanism, including the cross-museum behavior. However, it does not explicitly say when to avoid this tool or compare it to alternatives like browse_category or list_terms. The purpose is clear enough that an agent can infer usage, but explicit exclusions are missing.

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 toolsInspect
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.

Resources