smithsonian-mcp-server

Browse Smithsonian by Category

smithsonian_browse_category

Read-onlyIdempotent

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.

Input Schema

TableJSON Schema

Name	Required	Description
`mode`	Yes	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").
`rows`	No	Number of sample objects to return (default 10, max 50).
`start`	No	Pagination offset — 0-indexed. Page contiguously with start = page × rows.
`value`	Yes	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.

Output Schema

TableJSON Schema

Name	Required	Description
`cap`	No	The rows cap that was applied.
`mode`	No	Browse dimension used for this request (one of "museum", "culture", "period", "medium", "topic").
`error`	No	Present when the call failed. Absent on success.
`shown`	No	Number of sample objects returned.
`value`	No	Category value queried, as provided in the request.
`notice`	No	Guidance naming the input that retrieves the objects this page omitted.
`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 number of Smithsonian objects matching this category.
`sample_objects`	No	The requested page of objects matching the category, in upstream order. Empty when start is past the end of the category.
`museum_breakdown`	No	When mode is not "museum": top contributing museums from the sample, helping plan museum-focused follow-up searches.
`truncationCeiling`	No	Total matching objects (upper bound for omitted items).

Schema Changelog

Changes observed during successful MCP inspections.

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": [
+      "mode",
+      "value",
+      "total_count",
+      "sample_objects",
+      "museum_breakdown"
+    ]
+  },
+  {
+    "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: `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"
+          ],
+          "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: -[
-  "mode",
-  "value",
-  "total_count",
-  "sample_objects",
-  "museum_breakdown"
-]

Changed1 schema field changedJul 26, 2026

changedInput schema / properties / value / description

Previous value: -"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."New value: +"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."

Changed4 schema fields changedJul 26, 2026

changedInput schema / properties / mode / description

Previous value: -"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\")."New value: +"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\")."

changedInput schema / properties / mode / enum

Previous value: -[
-  "museum",
-  "culture",
-  "period",
-  "medium"
-]New value: +[
+  "museum",
+  "culture",
+  "period",
+  "medium",
+  "topic"
+]

changedInput schema / properties / value / description

Previous value: -"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\"). Smithsonian uses a controlled vocabulary — for museum (unit_code), culture, and period (date), call smithsonian_list_terms to find exact terms; medium (object_type) is not enumerable there, so harvest it from smithsonian_search_objects results."New value: +"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."

changedOutput schema / properties / mode / description

Previous value: -"Browse dimension used for this request (one of \"museum\", \"culture\", \"period\", \"medium\")."New value: +"Browse dimension used for this request (one of \"museum\", \"culture\", \"period\", \"medium\", \"topic\")."

Changed3 schema fields changedJul 26, 2026

changedInput schema / properties / mode / description

Previous value: -"Browse dimension: \"museum\" (by unit code), \"culture\" (by culture term), \"period\" (by decade like \"1940s\"), \"medium\" (by object type like \"Paintings\")."New value: +"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\")."

changedInput schema / properties / value / description

Previous value: -"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: a decade in \"NNNNs\" form (\"1940s\", \"1860s\"), required for that mode. medium: object type, usually plural (\"Paintings\", \"Aircraft\"). Smithsonian uses a controlled vocabulary — for museum (unit_code), culture, and period (date), call smithsonian_list_terms to find exact terms; medium (object_type) is not enumerable there, so harvest it from smithsonian_search_objects results."New value: +"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\"). Smithsonian uses a controlled vocabulary — for museum (unit_code), culture, and period (date), call smithsonian_list_terms to find exact terms; medium (object_type) is not enumerable there, so harvest it from smithsonian_search_objects results."

changedOutput schema / properties / sample_objects / 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."

AddedJul 25, 2026

TDQS

A5/5.0

Behavior5/5

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

Beyond the readOnly/openWorld/idempotent hints, the description discloses exact case-sensitive matching, emphasizes that medium casing variants are separate categories with independent totals, and states the return shape (total count, page, museum breakdown) plus pagination semantics. No contradictions with 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 dense but every sentence contributes: it opens with the core purpose, then flow constraints, then return and pagination, then the alternative tool. No filler; the structure flows logically from what→how→when-not.

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

Completeness5/5

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

For a complex 4-parameter tool with five modes, the description fully specifies required vocabulary resolution, exact matching behavior, the casing split, return contents, pagination, and routing to sibling tools. An output schema exists to cover return details, so nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but the description adds substantial practical meaning: it explains each mode's value format with concrete examples (unit codes, decade terms, BCE forms), the casing sensitivity trap for medium, and how to obtain valid values. This goes well beyond the schema's descriptions and is critical for correct invocation.

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 action ('browse Smithsonian objects') and scope ('within one exact category'), enumerates the five modes, and explicitly contrasts with the open-ended smithsonian_search_objects. This clearly delineates its purpose from siblings and gives the agent a precise mental model.

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 gives explicit when-to-use instructions: resolve museum/culture/period/topic via smithsonian_list_terms, harvest medium from smithsonian_search_objects, and 'For open-ended or topic discovery, start with smithsonian_search_objects instead.' It also warns against free-text values, making the usage constraints unambiguous.

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.

Browse Smithsonian by Category

Input Schema

Output Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources