smithsonian-mcp-server

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.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Free-text search. Use specific terms for precision (\"Tlingit totem pole\") or broad terms for browsing (\"quilt\")."
    },
    "filters": {
      "description": "Optional structured filters to narrow the search.",
      "type": "object",
      "properties": {
        "unit_code": {
          "description": "Museum unit code (e.g. \"NASM\", \"SAAM\", \"NMAH\", \"NMAAHC\", \"NMAI\", \"NPG\", \"CHNDM\", \"SIL\"); the National Museum of Natural History is indexed under discipline sub-units like \"NMNHBIRDS\" and \"NMNHPALEO\", not a bare \"NMNH\". The full set is enumerable via smithsonian_list_terms (field \"unit_code\").",
          "type": "string"
        },
        "object_type": {
          "description": "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.",
          "type": "string"
        },
        "date": {
          "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"
        },
        "culture": {
          "description": "Culture term from the controlled vocabulary — often plural or qualified (e.g. \"Aztecs\", \"Plains Indian\"). The vocabulary is enumerable via smithsonian_list_terms (field \"culture\").",
          "type": "string"
        },
        "place": {
          "description": "Geographic place (e.g. \"United States of America\"). The full set is enumerable via smithsonian_list_terms (field \"place\").",
          "type": "string"
        },
        "topic": {
          "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"
        },
        "name": {
          "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"
        },
        "online_only": {
          "description": "When true, restrict to records carrying an indexed online_media_type value. That vocabulary covers digitized surrogates — finding aids, catalog cards, scanned books, full text, electronic resources — alongside images, 3D models, and video, and the surrogate types often have no deliverable media attached, so a match can still report has_media: false. Read has_media on each result to decide whether smithsonian_get_media will return anything.",
          "type": "boolean"
        },
        "cc0_only": {
          "description": "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.",
          "type": "boolean"
        }
      }
    },
    "rows": {
      "default": 20,
      "description": "Page size (default 20, max 100).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "start": {
      "default": 0,
      "description": "Pagination offset — 0-indexed. Use with rows for paging through large result sets.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "query"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "objects": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "record_id": {
            "type": "string",
            "description": "Unique object identifier — pass to smithsonian_get_object, smithsonian_get_media, or smithsonian_find_related."
          },
          "title": {
            "type": "string",
            "description": "Object title from the catalog."
          },
          "unit_code": {
            "type": "string",
            "description": "Museum unit code (e.g. \"NASM\", \"SAAM\", \"NMNHBIRDS\"). Use as a filter in future searches."
          },
          "museum_name": {
            "type": "string",
            "description": "Full museum name for the unit code. A few rarely-indexed archive sub-unit codes have no mapped name and fall back to the raw unit code."
          },
          "object_type": {
            "description": "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.",
            "type": "string"
          },
          "date": {
            "description": "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.",
            "type": "string"
          },
          "thumbnail_url": {
            "description": "Thumbnail image URL (~120px) if the object has online media.",
            "type": "string"
          },
          "is_cc0": {
            "type": "boolean",
            "description": "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."
          },
          "has_media": {
            "type": "boolean",
            "description": "True when the object carries deliverable online media items. This is the signal smithsonian_get_media reads, so it — not the online_only filter — predicts whether that call returns anything."
          }
        },
        "required": [
          "record_id",
          "title",
          "unit_code",
          "museum_name",
          "is_cc0",
          "has_media"
        ],
        "additionalProperties": false,
        "description": "Curated summary of a single Smithsonian catalog object."
      },
      "description": "Curated object summaries for the current page."
    },
    "total_count": {
      "type": "number",
      "description": "Total matching objects in the Smithsonian catalog before pagination."
    },
    "truncated": {
      "description": "True when matching objects remain past this page. False on a terminal or past-the-end page, where nothing is being withheld.",
      "type": "boolean"
    },
    "shown": {
      "description": "Number of objects returned in this page.",
      "type": "number"
    },
    "cap": {
      "description": "The rows cap that was applied.",
      "type": "number"
    },
    "truncationCeiling": {
      "description": "Total matching objects (upper bound for omitted items).",
      "type": "number"
    },
    "notice": {
      "description": "Guidance naming the input that retrieves the objects this page omitted.",
      "type": "string"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "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"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "objects",
        "total_count"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Enumerate the valid term vocabulary for an indexed Smithsonian filter field (unit_code, culture, place, date, online_media_type, topic). Terms are a controlled vocabulary — often plural or qualified (e.g. "Paintings", not "Painting") — so guessed filter values tend to return nothing. Returns a page of the field's distinct term values; large vocabularies (topic has 133k terms, place 114k) page via start and rows. For unit_code, each code is returned with its museum name and contains matches the name as well as the code, so a museum name resolves to its code in one call.

{
  "type": "object",
  "properties": {
    "field": {
      "type": "string",
      "enum": [
        "unit_code",
        "culture",
        "place",
        "date",
        "online_media_type",
        "topic"
      ],
      "description": "Indexed field to enumerate. Choices: unit_code (museum codes like \"NASM\"), culture (e.g. \"Aztecs\"), place (geographic terms), date (decade/era values like \"1920s\"), online_media_type (media formats like \"Images\", \"3D Models\"), topic (subject terms like \"Quilts\" — 133k terms, so pair it with contains)."
    },
    "start": {
      "default": 0,
      "description": "Pagination offset (0-indexed). Use with rows to page through large vocabularies.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "rows": {
      "default": 50,
      "description": "Number of terms to return per page (default 50, max 100).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "contains": {
      "description": "Case-insensitive substring filter on the term vocabulary — resolve a filter value (e.g. \"greek\") to its exact controlled-vocabulary term(s). For unit_code the substring also matches each code's museum name, so \"National Air and Space\" resolves to \"NASM\".",
      "type": "string"
    }
  },
  "required": [
    "field"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "field": {
      "type": "string",
      "description": "The enumerated field, as provided in the request."
    },
    "terms": {
      "type": "array",
      "items": {
        "type": "string",
        "description": "A term value — pass directly as the filter value in smithsonian_search_objects or smithsonian_browse_category."
      },
      "description": "The field's distinct term values for this page, in the Smithsonian index's native order. No per-term object counts are available upstream."
    },
    "total": {
      "type": "number",
      "description": "Total number of distinct terms for this field (the full vocabulary size; terms is one page of it)."
    },
    "labels": {
      "description": "Museum name for each unit_code on this page that has one — present only when field is \"unit_code\". A few rarely-indexed archive sub-unit codes have no mapped name and are absent from this map; their term is still returned in terms.",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "string"
      }
    },
    "truncated": {
      "description": "True when matching terms remain past this page. False on a terminal or past-the-end page, where nothing is being withheld.",
      "type": "boolean"
    },
    "shown": {
      "description": "Number of terms returned in this page.",
      "type": "number"
    },
    "cap": {
      "description": "The rows cap that was applied.",
      "type": "number"
    },
    "truncationCeiling": {
      "description": "Distinct terms available for this query (the full vocabulary, or the contains-match count) — upper bound for omitted items.",
      "type": "number"
    },
    "notice": {
      "description": "Guidance naming the input that retrieves the terms this page omitted, or how to broaden a contains filter that matched nothing.",
      "type": "string"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `no_terms`: The field returned no indexed terms. Other values are possible when a failure originates below the handler.",
              "examples": [
                "no_terms"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "field",
        "terms",
        "total"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Fetch a normalized catalog metadata projection for a Smithsonian object by its record_id (from smithsonian_search_objects results). Returns the exposed catalog fields — title, dates, description, makers, materials, dimensions, places, cultures, topics, exhibitions, credit line, identifiers, rights, and a media summary. The media summary is a count; full image URLs come from smithsonian_get_media.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Object record_id from smithsonian_search_objects results (e.g. \"nasm_A19670093000\")."
    }
  },
  "required": [
    "id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "record_id": {
      "type": "string",
      "description": "Unique object identifier."
    },
    "title": {
      "type": "string",
      "description": "Object title."
    },
    "unit_code": {
      "type": "string",
      "description": "Museum unit code."
    },
    "museum_name": {
      "type": "string",
      "description": "Full museum name. A few rarely-indexed archive sub-unit codes have no mapped name and fall back to the raw unit code."
    },
    "dates": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string",
            "description": "Date field label (e.g. \"Date\", \"Accession Date\")."
          },
          "value": {
            "type": "string",
            "description": "Date value string."
          }
        },
        "required": [
          "label",
          "value"
        ],
        "additionalProperties": false,
        "description": "A single labeled date entry."
      },
      "description": "All date fields in the catalog record."
    },
    "description": {
      "description": "Best available prose description (Summary, Physical Description, or Brief Description notes).",
      "type": "string"
    },
    "makers": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "role": {
            "type": "string",
            "description": "Role of the named party (e.g. \"Artist\", \"Manufacturer\", \"Pilot\")."
          },
          "name": {
            "type": "string",
            "description": "Name of the party."
          }
        },
        "required": [
          "role",
          "name"
        ],
        "additionalProperties": false,
        "description": "A single named party entry."
      },
      "description": "All named parties associated with this object."
    },
    "materials": {
      "type": "array",
      "items": {
        "type": "string",
        "description": "A material or physical description string."
      },
      "description": "Physical material descriptions."
    },
    "dimensions": {
      "type": "array",
      "items": {
        "type": "string",
        "description": "A dimension or measurement string."
      },
      "description": "Dimension and measurement strings."
    },
    "place": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string",
            "description": "Place field label."
          },
          "value": {
            "type": "string",
            "description": "Place name or description."
          }
        },
        "required": [
          "label",
          "value"
        ],
        "additionalProperties": false,
        "description": "A single labeled place entry."
      },
      "description": "Geographic place associations."
    },
    "culture": {
      "type": "array",
      "items": {
        "type": "string",
        "description": "A culture term."
      },
      "description": "Culture associations."
    },
    "topics": {
      "type": "array",
      "items": {
        "type": "string",
        "description": "A subject or topic term."
      },
      "description": "Subject and topic terms."
    },
    "exhibitions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Exhibition name."
          },
          "building": {
            "description": "Building or venue where the exhibition was held.",
            "type": "string"
          }
        },
        "required": [
          "name"
        ],
        "additionalProperties": false,
        "description": "A single exhibition entry."
      },
      "description": "Exhibition history."
    },
    "credit_line": {
      "description": "Attribution or credit string.",
      "type": "string"
    },
    "identifiers": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string",
            "description": "Identifier type (e.g. \"Accession Number\", \"Call Number\")."
          },
          "value": {
            "type": "string",
            "description": "Identifier value."
          }
        },
        "required": [
          "label",
          "value"
        ],
        "additionalProperties": false,
        "description": "A single labeled identifier."
      },
      "description": "All accession and catalog identifiers."
    },
    "object_rights": {
      "description": "Rights statement from the catalog.",
      "type": "string"
    },
    "is_cc0": {
      "type": "boolean",
      "description": "True when the object metadata is CC0 (open access). The Smithsonian Open Access corpus is CC0 throughout, so this flag rarely varies — read media_summary.has_cc0_images to predict whether smithsonian_get_media returns images."
    },
    "record_link": {
      "description": "Canonical Smithsonian Institution URL for this object.",
      "type": "string"
    },
    "media_summary": {
      "type": "object",
      "properties": {
        "count": {
          "type": "number",
          "description": "Total number of online media items, across all types (includes non-image media such as 3D models)."
        },
        "cc0_image_count": {
          "type": "number",
          "description": "Number of CC0 images smithsonian_get_media returns for this object. Lower than count when the object has non-image media (e.g. 3D models) or non-CC0 images."
        },
        "has_cc0_images": {
          "type": "boolean",
          "description": "True when at least one CC0 image is available (cc0_image_count > 0)."
        },
        "thumbnail_url": {
          "description": "Thumbnail URL from the first media item.",
          "type": "string"
        }
      },
      "required": [
        "count",
        "cc0_image_count",
        "has_cc0_images"
      ],
      "additionalProperties": false,
      "description": "Media availability summary. Call smithsonian_get_media for full image URLs."
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `not_found`: No object with the given ID exists in the Smithsonian catalog. `invalid_id`: The ID format is clearly malformed (empty string, whitespace only). Other values are possible when a failure originates below the handler.",
              "examples": [
                "not_found",
                "invalid_id"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "record_id",
        "title",
        "unit_code",
        "museum_name",
        "dates",
        "makers",
        "materials",
        "dimensions",
        "place",
        "culture",
        "topics",
        "exhibitions",
        "identifiers",
        "is_cc0",
        "media_summary"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Return every CC0 (open-access) image for a Smithsonian object at multiple resolutions. The tool never returns an empty list — it names the reason instead: an object with nothing digitized, an object whose media is entirely non-image (scanned books, 3D models, sound recordings), and an object whose images are entirely non-CC0 each fail with their own reason. Each image entry includes thumbnail (~120px), screen-size (~800px), and high-resolution JPEG/TIFF URLs with pixel dimensions. The cc0_only filter on smithsonian_search_objects surfaces objects that have downloadable CC0 images.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "record_id of the object (e.g. \"nasm_A19670093000\") from smithsonian_search_objects or smithsonian_get_object."
    }
  },
  "required": [
    "id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "record_id": {
      "type": "string",
      "description": "Smithsonian catalog record ID for the object."
    },
    "title": {
      "type": "string",
      "description": "Object title from the catalog record."
    },
    "is_cc0": {
      "type": "boolean",
      "description": "True when the object-level metadata is CC0. The Open Access corpus is CC0 throughout, so this rarely varies; the per-image is_cc0 flag is what gates delivery."
    },
    "images": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "media_id": {
            "type": "string",
            "description": "IDS media identifier."
          },
          "is_cc0": {
            "type": "boolean",
            "description": "True when this specific image is CC0 (may differ from the object-level flag). Always true on returned images — non-CC0 images are filtered out before the response."
          },
          "alt_text": {
            "description": "Accessibility alt text for the image.",
            "type": "string"
          },
          "description": {
            "description": "Extended accessibility description.",
            "type": "string"
          },
          "thumbnail_url": {
            "description": "Thumbnail URL (~120px).",
            "type": "string"
          },
          "screen_url": {
            "description": "Screen-size URL (~800px).",
            "type": "string"
          },
          "high_res_jpeg": {
            "description": "Full-resolution JPEG download when available.",
            "type": "object",
            "properties": {
              "url": {
                "type": "string",
                "description": "Direct download URL for the image."
              },
              "width": {
                "description": "Image width in pixels.",
                "type": "number"
              },
              "height": {
                "description": "Image height in pixels.",
                "type": "number"
              }
            },
            "required": [
              "url"
            ],
            "additionalProperties": false
          },
          "high_res_tiff": {
            "description": "Archival TIFF download when available.",
            "type": "object",
            "properties": {
              "url": {
                "type": "string",
                "description": "Direct download URL for the image."
              },
              "width": {
                "description": "Image width in pixels.",
                "type": "number"
              },
              "height": {
                "description": "Image height in pixels.",
                "type": "number"
              }
            },
            "required": [
              "url"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "media_id",
          "is_cc0"
        ],
        "additionalProperties": false,
        "description": "A single CC0 image item with resolution variants."
      },
      "description": "CC0-licensed images for this object."
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `not_found`: No object with the given ID exists in the Smithsonian catalog. `no_media`: The object exists but has no digitized online media. `no_images`: The object has digitized media, but none of it is an image — the media is entirely non-image types such as scanned books, 3D models, or sound recordings. `not_cc0`: The object has media but none of its images are CC0 open access. `invalid_id`: The ID is empty or contains only whitespace. Other values are possible when a failure originates below the handler.",
              "examples": [
                "not_found",
                "no_media",
                "no_images",
                "not_cc0",
                "invalid_id"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "record_id",
        "title",
        "is_cc0",
        "images"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Browse Smithsonian objects within one exact category — a single museum (mode "museum"), culture, indexed date term (mode "period"), object type (mode "medium"), or subject term (mode "topic"). The value must be an exact indexed category term, not free text: resolve museum, culture, period, and topic vocabulary with smithsonian_list_terms first (object_type is not enumerable there — harvest it from smithsonian_search_objects results, and treat each casing as its own category, since a harvested object_type covers only the casing it was written in). Returns the category total count, a page of matching objects, and a museum breakdown of that page; page the full category with start and rows. For open-ended or topic discovery, start with smithsonian_search_objects instead.

{
  "type": "object",
  "properties": {
    "mode": {
      "type": "string",
      "enum": [
        "museum",
        "culture",
        "period",
        "medium",
        "topic"
      ],
      "description": "Browse dimension: \"museum\" (by unit code), \"culture\" (by culture term), \"period\" (by indexed date term like \"1940s\" or \"500-1500\"), \"medium\" (by object type like \"Paintings\"), \"topic\" (by subject term like \"Quilts\")."
    },
    "value": {
      "type": "string",
      "description": "Category value appropriate to the mode. museum: a unit code like \"NASM\", \"SAAM\", or \"NMNHBIRDS\", matched literally and case-sensitively — not a museum name. culture: term, often plural or qualified (\"Aztecs\", \"Plains Indian\"). period: an indexed date term — commonly a decade (\"1940s\", \"1860s\"), but year ranges (\"500-1500\"), century terms (\"21st century\"), and BCE forms (\"-2500\", \"BCE 1000s\") are indexed too. medium: object type, usually plural (\"Paintings\", \"Aircraft\"). topic: subject term (\"Quilts\", \"Aviation\"). Smithsonian uses a controlled vocabulary — for museum (unit_code), culture, period (date), and topic, call smithsonian_list_terms to find exact terms; medium (object_type) is not enumerable there, so harvest it from smithsonian_search_objects results. Every mode matches its value exactly and case-sensitively, and for medium that split is load-bearing: casing variants are indexed as SEPARATE categories, each reporting its own total_count (\"button\" and \"Button\" are different categories, and neither casing is reliably the larger), so browse the variants of a harvested value rather than assuming one covers the concept."
    },
    "rows": {
      "default": 10,
      "description": "Number of sample objects to return (default 10, max 50).",
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    },
    "start": {
      "default": 0,
      "description": "Pagination offset — 0-indexed. Page contiguously with start = page × rows.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "mode",
    "value"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "mode": {
      "type": "string",
      "description": "Browse dimension used for this request (one of \"museum\", \"culture\", \"period\", \"medium\", \"topic\")."
    },
    "value": {
      "type": "string",
      "description": "Category value queried, as provided in the request."
    },
    "total_count": {
      "type": "number",
      "description": "Total number of Smithsonian objects matching this category."
    },
    "sample_objects": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "record_id": {
            "type": "string",
            "description": "Object identifier — pass to smithsonian_get_object or smithsonian_get_media."
          },
          "title": {
            "type": "string",
            "description": "Object title."
          },
          "unit_code": {
            "type": "string",
            "description": "Museum unit code."
          },
          "thumbnail_url": {
            "description": "Thumbnail image URL if available.",
            "type": "string"
          },
          "is_cc0": {
            "type": "boolean",
            "description": "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."
          }
        },
        "required": [
          "record_id",
          "title",
          "unit_code",
          "is_cc0"
        ],
        "additionalProperties": false,
        "description": "A sample object from the requested page of category matches."
      },
      "description": "The requested page of objects matching the category, in upstream order. Empty when start is past the end of the category."
    },
    "museum_breakdown": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "unit_code": {
            "type": "string",
            "description": "Smithsonian unit code for this museum (e.g. \"NMNHPALEO\", \"SAAM\")."
          },
          "museum_name": {
            "type": "string",
            "description": "Full name of the museum. A few rarely-indexed archive sub-unit codes have no mapped name and fall back to the raw unit code."
          },
          "count": {
            "type": "number",
            "description": "Estimated object count from sample (not exact)."
          }
        },
        "required": [
          "unit_code",
          "museum_name",
          "count"
        ],
        "additionalProperties": false,
        "description": "A single museum contribution entry."
      },
      "description": "When mode is not \"museum\": top contributing museums from the sample, helping plan museum-focused follow-up searches."
    },
    "truncated": {
      "description": "True when matching objects remain past this page. False on a terminal or past-the-end page, where nothing is being withheld.",
      "type": "boolean"
    },
    "shown": {
      "description": "Number of sample objects returned.",
      "type": "number"
    },
    "cap": {
      "description": "The rows cap that was applied.",
      "type": "number"
    },
    "truncationCeiling": {
      "description": "Total matching objects (upper bound for omitted items).",
      "type": "number"
    },
    "notice": {
      "description": "Guidance naming the input that retrieves the objects this page omitted.",
      "type": "string"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `invalid_category`: The category value matched no objects — a browse category is an exact indexed facet, so a zero match means the value did not resolve to retrievable objects. Other values are possible when a failure originates below the handler.",
              "examples": [
                "invalid_category"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "mode",
        "value",
        "total_count",
        "sample_objects",
        "museum_breakdown"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

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.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "record_id of the anchor object (e.g. \"nasm_A19670093000\") from smithsonian_search_objects or smithsonian_get_object."
    },
    "limit": {
      "default": 10,
      "description": "Maximum number of related objects to return (default 10, max 20).",
      "type": "integer",
      "minimum": 1,
      "maximum": 20
    },
    "start": {
      "default": 0,
      "description": "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.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "anchor": {
      "type": "object",
      "properties": {
        "record_id": {
          "type": "string",
          "description": "Smithsonian catalog record ID for the input object."
        },
        "title": {
          "type": "string",
          "description": "Title of the input object from the catalog."
        },
        "unit_code": {
          "type": "string",
          "description": "Museum unit code for the input object (e.g. \"NASM\")."
        }
      },
      "required": [
        "record_id",
        "title",
        "unit_code"
      ],
      "additionalProperties": false,
      "description": "Summary of the anchor object used to drive the fan-out searches."
    },
    "related": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "record_id": {
            "type": "string",
            "description": "Object identifier — pass to smithsonian_get_object or smithsonian_get_media."
          },
          "title": {
            "type": "string",
            "description": "Object title."
          },
          "unit_code": {
            "type": "string",
            "description": "Museum unit code."
          },
          "museum_name": {
            "type": "string",
            "description": "Full museum name. A few rarely-indexed archive sub-unit codes have no mapped name and fall back to the raw unit code."
          },
          "thumbnail_url": {
            "description": "Thumbnail URL if available.",
            "type": "string"
          },
          "is_cc0": {
            "type": "boolean",
            "description": "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."
          },
          "similarity_signals": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A metadata signal that connected this object to the anchor (e.g. \"culture: Plains Indian\")."
            },
            "description": "Metadata terms that connected this object to the anchor."
          }
        },
        "required": [
          "record_id",
          "title",
          "unit_code",
          "museum_name",
          "is_cc0",
          "similarity_signals"
        ],
        "additionalProperties": false,
        "description": "A related object with its connecting metadata signals."
      },
      "description": "Related objects interleaved across the fan-out signals so each signal contributes. Empty when no related objects were found across all fan-out searches."
    },
    "search_signals_used": {
      "type": "array",
      "items": {
        "type": "string",
        "description": "A metadata signal used for a fan-out search."
      },
      "description": "Metadata fields that drove the fan-out searches."
    },
    "signals": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "signal": {
            "type": "string",
            "description": "Matches an entry in search_signals_used and in related[].similarity_signals."
          },
          "row_count": {
            "type": "number",
            "description": "True upstream match count for this signal, uncapped — it can exceed the 5000-per-signal depth this tool's own paging reaches."
          },
          "search_continuation": {
            "type": "object",
            "properties": {
              "query": {
                "type": "string",
                "description": "Pass verbatim as smithsonian_search_objects's query. Empty when the signal is expressed entirely through filters."
              },
              "filters": {
                "description": "Pass verbatim as smithsonian_search_objects's filters. Omitted when the signal's constraint is already carried entirely by query.",
                "type": "object",
                "properties": {
                  "culture": {
                    "description": "smithsonian_search_objects filters.culture value.",
                    "type": "string"
                  },
                  "object_type": {
                    "description": "smithsonian_search_objects filters.object_type value.",
                    "type": "string"
                  },
                  "date": {
                    "description": "smithsonian_search_objects filters.date value.",
                    "type": "string"
                  },
                  "name": {
                    "description": "smithsonian_search_objects filters.name value.",
                    "type": "string"
                  },
                  "topic": {
                    "description": "smithsonian_search_objects filters.topic value.",
                    "type": "string"
                  }
                },
                "additionalProperties": false
              }
            },
            "required": [
              "query"
            ],
            "additionalProperties": false,
            "description": "Exact smithsonian_search_objects input that reproduces this signal's full match set, at any depth."
          }
        },
        "required": [
          "signal",
          "row_count",
          "search_continuation"
        ],
        "additionalProperties": false,
        "description": "One fan-out signal with its true size and its retrieval path."
      },
      "description": "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."
    },
    "truncated": {
      "description": "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).",
      "type": "boolean"
    },
    "shown": {
      "description": "Number of related objects returned.",
      "type": "number"
    },
    "cap": {
      "description": "The limit cap that was applied.",
      "type": "number"
    },
    "truncationCeiling": {
      "description": "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.",
      "type": "number"
    },
    "notice": {
      "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"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "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"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "anchor",
        "related",
        "search_signals_used",
        "signals"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}